Message Boards Message Boards

Making a website / GitBook for a Mathematica tutorial

Posted 7 years ago

Building the Tutorial

This is a successor post to one a few days ago, where I demonstrated how to build websites in the Wolfram Cloud.

A few days ago I remembered a little tutorial notebook I had written for some friends about a year back and wanted to make it more useable.

I'd also had a conversation with people on the StackExchange where halirutan had suggested linking interactivity in the tutorial. I don't have the cloud credits (or patience, given the idiosyncrasies of the cloud) to roll an entirely cloud-notebook tutorial, so I decided to use a different thing I'd played with where I use a sandboxed cloud-notebook in an iframe to add dynamic interactivity.

I decided to chop my tutorial notebook into its different sections and make a page for each subsection. I'd then link each page to the next page via some ID (like 1.1.1 for chapter 1, section 1, page 1) and add a cloud-notebook footer to the template.

To start, though, I needed a theme, so I merged a W3 template and my existing PacletServer theme to make a new theme with a side-bar and stuff to hold the page index.

The actual process of building the site theme is boring, but it was certainly the most time consuming part of the whole project.

Then I just made a new notebook for each section where I basically just changed the metadata for each, e.g.:

asddd

And then used the website builder palette I developed to build and deploy my site.

Actual Site

Now here's the fun part. The actual site lives here: https://www.wolframcloud.com/objects/b3m2a1.testing/tutorial/main.html

asddd2

This would of course be much nicer with a better domain name

I used that ID I mentioned (and which you can see in the notebook metadata) to build in an ordering and then the template builds that out into a proper documentation layout.

You can then click on a any of those pages to read that piece of the tutorial:

asddd

There's a little thumb that sticks to the bottom of the window which you can click on to open a cloud notebook to test the code snippets in:

asddd

And clicking on it again will minimize it:

asddd

This is I think the best feature of the entire enterprise, as it combines the convenience of cloud notebook with the responsiveness of a static site.

Finally, each page has a set of buttons to go to the next / previous topic in the tutorial:

asddd

The site map lives in the side bar (which is hidden on small screens and is opened via a menu button):

asddd

And, like all pelican-esque sites, the tutorial website has aggregation pages, e.g. by category:

asddd

asddd

I think that's all of the features, so now we'll move to how you, dear reader, can make something like this for yourself

Making your own

I've included this as a template in BTools so that you can copy it. It is not mirrored in the SiteBuilder subpaclet.

You can make your own theme (or just repurpose mine), add features, etc. and deploy the whole thing with the SiteBuilder palette

Getting a better domain name

Finally, as I mentioned previously, it would be much nicer to send someone to a different domain name than "wolframcloud.com/objects/actual/domain/info/here".

The "wolframcloud.com/objects" hides the meaning behind the URL and scares off visitors (or at least makes them think more before clicking).

If you agree, be sure to send support an email. WRI has in the past bowed to user pressure on things like this.

POSTED BY: b3m2a1 ​ 
2 Replies
Posted 7 years ago

This now exists as a GitBook too: https://b3m2a1.gitbooks.io/mathematica-tutorial/content/

GitBook

I wrote a little script to turn a website generated with the SiteBuilder package into a GitBook ready website:

gitBookCopyContent[srcDir_, bookDir_] :=
  With[{
    main = FileNameJoin@{srcDir, "content"}
    },
   Export[
    FileNameJoin@{bookDir, "README.md"},
    StringSplit[
      Import[FileNameJoin@{main, "pages", "About.md"}, "Text"],
      "\n\n",
      2
      ][[2]],
    "Text",
    CharacterEncoding -> "UTF8"
    ];
   Map[
    If[! MatchQ[FileNameTake[#], "pages" | "posts" | ".git"],
      With[{f = FileNameJoin@{bookDir, StringTrim[#, main]}},
       Which[DirectoryQ@#,
        If[FileExistsQ@f,
         DeleteDirectory[f, DeleteContents -> True]
         ];
        CopyDirectory[#, f],
        MatchQ[FileExtension[#], "png" | "jpeg"],
        CopyFile[#, f, OverwriteTarget -> True]
        ]
       ]
      ] &,
    FileNames["*", main]
    ]
   ];
gitBookExportMD[outdir_, bookDir_, content_] :=
  KeyValueMap[
   Function[
    With[{f =
       FileNameJoin@Flatten@
         {
          bookDir,
          FileNameSplit@
           StringTrim[#, outdir]
          }
      },
     If[! DirectoryQ@DirectoryName@f,
      CreateDirectory[DirectoryName@f, 
       CreateIntermediateDirectories -> True]
      ];
     Export[
      f,
      StringJoin[
       StringReplace[#2,
         { 
          "{{" -> "{ {",
           "}}" -> "} }",
          "{filename}" ->
           URLBuild@
            ConstantArray["..", 
             FileNameDepth[StringTrim[#, outdir]] - 2
             ]
          }
         ] /.
        StringExpression[a___] :> a
       ],
      "Text",
      CharacterEncoding -> "UTF8"
      ]
     ]
    ],
   content
   ];
gitBookMakeSummary[outdir_,  bookDir_, metas_] :=

  Module[{data,  cells, nb},
   data =
    GroupBy[First -> Last] /@

     GroupBy[#[[1, 1]] & -> (#[[1, 2]] -> #[[2]] &)]@
      KeyValueMap[
       URLParse[#2["Path"], "Path"][[;; 2]] ->
         <|

          "Path" ->
           URLBuild[FileNameSplit@StringTrim[#, outdir]],
          "Title" -> #2["Title"]
          |> &,
       metas
       ];
   cells =
    KeyValueMap[
     Cell[
       CellGroupData[Flatten@{
          Cell[#, "Section"],
          KeyValueMap[
           Cell[
             CellGroupData[
              Flatten@{
                Cell[#, "Subsection"],
                Map[
                 Cell[
                   TextData[
                    ButtonBox[#Title,
                     BaseStyle -> "Hyperlink",
                    ButtonData ->
                    {

                    FrontEnd`FileName[
                    Evaluate@URLParse[#Path, "Path"]], 
                    None
                    }
                    ]
                    ],
                   "Item"
                   ] &,
                 #2
                  ]
                }
              ]
             ] &,
           #2
           ]
          }
        ]
       ] &,
     data
     ];
   CheckAbort[
    nb =
     CreateDocument[
      Prepend[
       cells,
       Cell[
        TextData[
         ButtonBox[
          "Introduction",
           BaseStyle -> "Hyperlink",
          ButtonData ->
           {
            "README.md", 
            None
            }
          ]
         ],
        "Item"
        ]
       ],
      Visible -> False,
      StyleDefinitions -> 
       FrontEnd`FileName[{"BTools"}, "NotebookToMarkdown.nb"],
      NotebookFileName ->
       FileNameJoin@{bookDir, "SUMMARY.nb"}
      ];
    NotebookMarkdownSave[nb];
    NotebookClose[nb];
    DeleteFile[FileNameJoin@{bookDir, "SUMMARY.nb"}];,
    NotebookClose[nb]
    ];
   ];
gitBookBuild[srcDir_, bookDir_] :=
  Module[
   {outdir, content},
   gitBookCopyContent[srcDir, bookDir];
   outdir =
    FileNameJoin@{srcDir, "content", "posts"};
   content =
    AssociationMap[
     With[{split = StringSplit[Import[#, "Text"], "\n\n", 2]},
       <|
        "Meta" ->
         Association@
          Map[
           Rule @@ StringTrim@StringSplit[#, ":", 2] &,
           StringSplit[split[[1]], "\n"]
           ],
        "Body" ->
         split[[2]]
        |>
       ] &,
     FileNames["*.md", outdir, \[Infinity]]
     ];
   gitBookExportMD[outdir, bookDir, content[[All, "Body"]] ];
   gitBookMakeSummary[outdir, bookDir, 
    SortBy[
     content[[All, "Meta"]],
     ToExpression[StringSplit[#ID, "."]] &
     ]
    ];
   bookDir
   ];

This doesn't mirror over the theme, but it gets the job done

I use it like this:

gitBookBuild[
  FileNameJoin@{$WebSiteDirectory, "tutorial"},
  FileNameJoin@{$UserDocumentsDirectory, "GitHub", 
    "mathematica-tutorial"}
  ];

and then commit the mirrored repo on GitHub that GitBook builds from

POSTED BY: b3m2a1 ​ 

enter image description here - Congratulations! This post is now a Staff Pick as distinguished by a badge on your profile! Thank you, keep it coming!

POSTED BY: EDITORIAL BOARD
Reply to this discussion
Community posts can be styled and formatted using the Markdown syntax.
Reply Preview
Attachments
Remove
or Discard

Group Abstract Group Abstract