Guides for SE student projects »

Using MarkBind for project documentation

If you are working with a forked repo that is using MarkBind already, refer to this guide instead.

MarkBind is a tool for generating static websites from markdown-like text, particularly suitable for text-heavy websites such as software project documentation.

Given below is some information that may be useful when you want to update documentation in a project that uses MarkBind.

Installation

Updating documents

MarkBind is a superset of Markdown. Refer to the MarkBind user guide for more details.

First, start the live preview: Unless the change is trivial, preview how your edits will appear in the generated website. Use MarkBind live preview mode to see updates as you edit the source file. To start the live preview mode,

  1. Open a command prompt.
  2. Navigate to the documentation root (in most projects, the documentation root is [project root]/docs -- if you are not sure, look for the folder containing the site.json file).
  3. Run the markbind serve command. That will open the generated website in your default browser.
  4. In the browser, navigate to the page you want to modify.

Next, edit the files you want:

  1. Edit the source files (usually, .md files).
  2. When you save the file, the live preview will update to reflect the new contents (after a few seconds).

While live preview can pick up most changes, it may miss certain ones (e.g., changes to files in the _markbind folder or changes to nunjucks macros). Furthermore, some syntax errors in your code can cause the live preview to crash. In those cases, just stop the server (Ctrl+C on Windows) and start it again.

Automating PR previews, deployments

Project admins can,

  • set up Netlify to give a preview of how a PR can affect the generated website. More info here.
  • set up Travis to automatically generate and deploy the project website when new code is pushed. More info here