Documentation guide

Setting up and maintaining the project website:

  • We use MarkBind to manage documentation.
  • The docs/ folder is contains the source files for the documentation website.
  • To learn how set it up and maintain the project website, follow the MarkBind User Guide.
Quick Start 🚀

Introduction

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

Prerequisites

  • a basic knowledge of Markdown and HTML syntax
  • a basic knowledge of running CLI commands

Installation

  • install Node.js 16 or higher
  • install Graphviz (for generating diagrams)
    • For Mac, you can use Homebrew to install Graphviz: brew install graphviz
    • For Windows, you can use Chocolatey to install Graphviz: choco install graphviz
    • For Linux, you can use your package manager to install Graphviz: sudo apt install graphviz
  • open the project and go to the docs folder: cd docs
  • install dependencies, only needed once when setting up the project: npm ci

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 npm run 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 Deployments

The docs site can be deployed automatically with GitHub Actions. The .github/workflows/docs.yml file provides a ready made script to achieve it. More info here.

  • Note these points when adapting the documentation to a different project/product:
    • The markbind/tweaking the page structure and markbind/site.json pages have information on how to update site-wide elements such as the top navigation bar.
    • 💡 In addition to updating content files, you might have to update the config files docs\site.json and the layout files docs\_markbind\layouts\default.md (which contains a reference to AB-3 that comes into play when converting documentation pages to PDF format).
  • If you are using Intellij for editing documentation files, you can consider enabling 'soft wrapping' for *.md files, as explained in se-edu/guides Intellij IDEA: Useful settings

Style guidance:

Diagrams:

Converting a document to the PDF format: