Guides for SE student projects »

Working with a forked MarkBind site

This guide explains how to work with a MarkBind site that has been forked on GitHub, taking addressbook-level3 (AB3) as an example).

Assumptions (these are true for AB3):

  1. Documentation source files are in the [project root]/docs folder.
  2. The project comes with a package.json file, specifying the dependencies.
  3. The site is to be deployed on GitHub Pages, using GitHub Actions CI.

Initiating the site

Once you have forked the repo into your own GitHub org, you need to adapt the site to your project (e.g., change project name) and publish the MarkBind site on GitHub. Given below are the steps for doing that.

Step 1 Give org level write permissions to GitHub Actions as follows (reason: GitHub actions will needs write permissions to push your MarkBind site onto the gh-pages branch of your repo):

  1. Go to the Settings  tab of your GitHub org that contains the fork (not the settings tab of your fork).
  2. On the navigation menu on the left, expand on the Actions  menu and click on the   General  option.
  3. Scroll to the Workflow permissions section at the bottom of the page.
  4. Choose Read and write permissions option.

Step 2 Update the site configs to match your fork

When adapting the documentation to a new fork that evolves/morphs the upstream project into a different project/product, in addition to updating content files, you need to update config files to match your own project. In AB3, these are the config files you need to update:

[project root] ├── .github │ └── workflows │ └── docs.yml (change baseUrl in this file e.g.,baseUrl: '/addresssbook-level3' -> baseUrl: '/tp') └── docs ├── _markbind │ └── layouts │ └── default.md (update product name in this file e.g., AB-3 -> MyProduct) └── site.json (change titlePrefix in this file e.g., titlePrefix: "MyProduct")

baseUrl in site.json is used for links when running the site locally, and should remain as empty e.g., baseUrl: "".
baseUrl in docs.yml is used for links in the deployed site, and should match the repo name e.g., baseUrl: '/tp'.

Step 3 Commit the config changes and push to your fork.

Step 4 Enable GitHub Pages of your fork.

  1. Go to the Settings  tab of your fork (not the org, as you did in step 1).
  2. Click   Pages  on the menu on the left edge of page.
  3. Set the Source as:  Deploy from a branch branch gh-pages branch and /(root) folder and click  Save .
    gh-pages is a branch auto-created by GitHub, when generating the website for a repo.
  4. After CI has run (which might take 1-2 minutes), your MarkBind site will be available at http(s)://<organization_name_in_lower_case>.github.io/<repository> e.g., https://ay2324s2-csxxxx-f18.github.io/tp

Next ... Update content, commit, and push. For future updates to the site, all you need to do is update content (usually, in *.md files), commit the changes, and push to your fork. The published MarkBind site will be updated automatically after the CI has run.

Read the two sections below to find how to install MarkBind in your computer and use it to live-preview changes as you edit source files.

Site-wide settings

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.

Installing MarkBind

For any non-trivial site updates, you would want to edit the source files locally, and preview the generated site first (to ensure the edits produces the intended outcome), before publishing the changes. For that, you need to install MarkBind in your computer. Given below are the steps, which assumes you already have the source files for a MarkBind-compatible Website e.g., AB3.

  1. Ensure you have Java 8 or higher installed
  2. Install Node.js 16 or higher
  3. Install Graphviz (for generating diagrams)
    • Windows: Graphviz not required. There will be warning about missing Graphviz, which you can ignore.
    • Mac: you can use Homebrew to install Graphviz: brew install graphviz
    • For Linux, you can use your package manager to install Graphviz: sudo apt install graphviz
  4. Open a terminal and navigate to the root folder of the Website which contains the package.json file (in AB3, this would be [project root]/docs folder).
  5. To install MarkBind (and other dependencies), run the command npm ci

To update MarkBind to a newer version (at a later time), run the following command from the same folder you ran the npm ci command:

npm install markbind-cli@latest --save-dev

Updating documents

MarkBind is a superset of Markdown. Refer the MarkBind UG: Authoring Contents for more details on the syntax. Given below is the recommended workflow for any non-trivial changes to this docs site.

  1. Install MarkBind (as described in the section above), if you haven't done so already.
  2. Open a terminal and navigate to the [project root]/docs folder.
  3. Run the npm run serve command. That will open the generated website in your default browser in a live preview mode.
  4. In the browser, navigate to the page you want to preview.
  5. Edit the source files (usually, *.md files). 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 (e.g., Ctrl+C on Windows) and start it again.

Recommendation: Enable soft-wrapping in your code editor for *.md files. For example, as explained in Intellij IDEA: Useful settings guide.

Generating a Table of Content for a page: As MarkBind pages automatically generate a page navigation menu (which appears on the top right edge of the page), there is no need to manually insert a ToC into a page.
Furthermore, when saving the page as a PDF, you can make the page navigation menu appear as a ToC in the generated PDF, by inserting <page-nav-print /> in the page where you want the ToC to appear.

Working with UML diagrams

MarkBind has built-in support for PlantUML diagrams. See the this page of the MarkBind User Guide to find how to use PlantUML with MarkBind.

Also see se-edu/guides Using PlantUML for useful info on using PlantUML in a project such as AB3.