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 are some information useful for when you want to update documentation in a project that uses MarkBind.

Installation

Updating documents

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

First, start the live preview: Unless it is a trivial change, you would want to see how your change to the documentation source files will reflect in the generated website. You can use the MarkBind live preview mode to preview the generated website as you update the source file. To start the live preview mode,

  1. Open a command prompt.
  2. Navigate to the 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 not be able to pick up certain changes (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