Slidoc: A slide-oriented document management system using Markdown

Slidoc manages a collection of lectures and exercises written using Markdown, which is a very simple and popular markup syntax. The lectures and exercises can include text, images, interactive questions, and equations (using LaTeX notation).

Markdown files are plain text files saved using extension .md. They can be edited using text editors like Emacs, vi, Atom, and StackEdit. Slidoc can publish the Markdown files as static HTML files and Jupyter notebooks. It can also create a table of contents, generate an index, manage questions and analyze concept dependencies.

The HTML files generated by Slidoc can be shared via email or hosted using free resources such as public Dropbox folders, Github project web sites etc.

The design goals of Slidoc documents are:

Easy to write.
Easy to read.
Easy to interact with.
Track understanding of concepts.

This README file provides documentation, examples and tests for Slidoc.

Notes: Using the widely-used Markdown file format, with some extensions for equations and interactivity, accomplishes the first goal. With this format, plain text editors and many other open source tools (such as Pandoc) can be used to edit and process the files. Version control is easy and sites like GitHub can be used to store and share the files.

The remaining goals are achieved using plain vanilla HTML files with embedded Javascript, allowing easy navigation between slides and lectures. The format is mobile-friendly and allows "index navigation", i.e., scrolling through portions of different lectures that discuss same concept. The embedded Javascript also provides interactivity, allowing users to answer embedded questions, tallying scores and tracking understanding of concepts.

Tags: Slidoc, design goals; slides, Markdown

Installation

Slidoc currently works only on Unix-like systems, such as OS X, Linux, etc. (A Windows port should not be too difficult, but is not currenly a priority.)

To install, download the latest release from https://github.com/mitotic/slidoc/releases and unzip/untar it to create the slidoc-version-number directory containing several Python, HTML, CSS, and Javascript files.

To test the installation, create a temporary directory slidoc-version-number/temp and set that as your working directory:

cd slidoc-version-number/temp

src/slidoc.py is the command line Markdown to HTML converter. To test it, type the following terminal command in the temp directory:

../src/slidoc.py ../README.md

This will create the file README.html. This is a (mostly) self-contained HTML file with Javascript embedded for interactivity, and can be viewed in a browser.

slidoc.py includes a simple web server for displaying HTML ouput, and can be invoked using the following terminal command:

../src/slidoc.py -p 8082 README.md

This will display the converted version of README.md in a browser window using the URL http://localhost:8082. You can edit README.md file using any text editor, and the browser display will automatically update every time you save the file in the text editor, providing a live preview of the HTML document.

Dependencies

Slidoc has minimal external dependencies. The HTML converter slidoc.py uses mistune for HTML exports, which is already included in the src directory for convenience. Optionally, you may install the pygments module for code highlighting.

HTML documents produced by Slidoc automatically load the Mathjax library to display equations. This means that equations will not render without an internet connection.

The server program sdserver.py requires the Tornado web server to be installed.

Using Slidoc with Windows 10 Subsystem for Linux

https://docs.microsoft.com/en-us/windows/wsl/install-win10

Open PowerShell as Administrator and run:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Reboot the system

Open Microsoft Store and install a Linux distribution (such as Ubuntu)

Enter Unix username and password (may be different from Windows)

From now on, Linux can be accessed by running bash.exe

In the terminal, run

sudo apt install python-minimal
sudo apt update -y 
sudo apt install python-pip
git clone https://github.com/mitotic/slidoc.git
cd slidoc/src
python slidoc.py -p 8080 ../README.md

Open the URL http://localhost:8080 using a browser

Lecture management

Say the root directory is Course. Typically, all lectures would be stored in a Lectures subddirectory with ordered names like prefix-lecture01.md.

To export some or all lectures to html format for web publishing, create a sub-directory, say Publish. In that directory, type:

slidoc.py --all=all.html ../Lectures/prefix-lecture??.md

The above command will combine all the lectures, table of contents and index into a single file all.html, which can be published on the web or shared.

Alternatively, the --indexed=toc,ind,qind option can be used instead of --all to generate separate HTML files. This will create files named prefix-lecture01.html and so on in the Publish directory. Additionally, it will create three files, toc.html (table of contents) , ind.html (concept index), and qind.html (question index). These are static web files which can be served from any web server. In addition to free services such as public Dropbox folders and Github project web sites, low-cost web hosting services like Site44 and NearlyFreeSpeech.net are also worth considering.

Tags: lecture management: index, concepts

Notes: The --indexed=,ind, option can be used with null arguments to control generation of index files.

Editing Markdown

Markdown files are plain text files saved using extension .md. They can be edited using text editors like Emacs, vi, Atom, and StackEdit. The Markdown Preview Plus package for Atom supports live rendering of Markdown (with math) while you edit. There is also a Chrome extension of the same name to render Markdown in the browser.

Tags: Markdown, editing

Slidoc document structure

Slidoc recognizes several extensions to standard Markdown to process slides in a lecture.

Each file begins with a Level 1 title header (# Lecture Title) in the first slide.
Each new slide may have an optional Level 2 header (## Slide title) (Higher-level headers may also be used, but they will not be numbered.)
If a Level 2 header is not present at the start of a slide, a horizontal rule, i.e., a line with three or more horizontal dashes (---), may be used to indicate the start of a slide.
Since the horizontal rule denotes the end of the slide, by default, Slidoc will not recognize the use of dashes to underline Level 2 headers, even though Markdown syntax allows it.

Notes: Any Level 1 header other than the first one will be treated like a Level 2 header.

Tags: :Slidoc, document structure

Tags and Notes

Two additional pieces of information may optionally be included in each slide: a list of tags/concepts and additional notes. A tag list may appear anywhere in the slide, but notes can only appear at the very end of the slide.

Example:

Tags: primary topic1; primary topic2, subtopic2: secondary topic3, subtopic3; secondary topic4; ...

Notes: Additional material

Tag/concept lists are used generate an automatic index. Indexing is done separately for regular slides and question slides. Slidoc supports concept chain navigation. Starting from the index, you can easily navigate between all places in the document where a particular concept is discussed.

Tags: concepts, list; concepts, multiple: concepts, tracking

Notes: Tag lists have two parts: primary tag list and secondary tag list, separated by a colon. Either part may be omitted. (If there are no primary tag, then a colon should precede the secondary tag list.)

Tag lists are semicolon-separated. Each tag uses the syntax topic, subtopic where topic or subtopic is a space-separated phrase, with subtopic being optional. Tags are not visible during a slideshow, but are displayed in the printed version of the lecture.

Notes are additional material that appear below the main content. In slideshow mode (see below), notes are normally shown collapsed (or hidden) in the slide for compactness, but may be expanded and scrolled into view.

Slideshow mode and quick navigation

Slidoc features a built-in "slideshow" mode, allowing you to switch seamlessly between scroll view and slide view anywhere in the document. Slide view is enabled by clicking on the square (<span>▣</span>) icon on the bottom left. The Escape key may also be used to enter/exit slide mode. Pressing ? during a slideshow displays a list of keyboard shortcuts.

The slideshow mode can be used for quick navigation around the document:

Press Escape to enter slideshow
Use h, e, p, n, or left/right arrow keys to move around quickly
Press Escape to exit

Slidoc

Install / Use

README