Migrate docs to MarkBind

Let's migrate the docs site from Jekyll to MarkBind.

Primary author: @tlylt in se-edu/addressbook-level3/pull/156
Further tweaks: @damithc in se-edu/addressbook-level3/pull/206

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: MarkBind Action
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Graphviz
+        run: sudo apt-get install graphviz
+      - name: Install Java
+        uses: actions/setup-java@v3
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+      - name: Build & Deploy MarkBind site
+        uses: MarkBind/markbind-action@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          rootDirectory: './docs'
+          baseUrl: '/addressbook-level3' # replace with your repo name
+          version: '^5.1.0'

.gitignore

@@ -21,3 +21,4 @@ src/test/data/sandbox/
 # MacOS custom attributes files created by Finder
 .DS_Store
 docs/_site/
+docs/_markbind/logs/

docs/.gitignore

@@ -0,0 +1,23 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+_markbind/logs/
+
+# Dependency directories
+node_modules/
+
+# Production build files (change if you output the build to a different directory)
+_site/
+
+# Env
+.env
+.env.local
+
+# IDE configs
+.vscode/
+.idea/*
+*.iml

docs/AboutUs.md

@@ -1,9 +1,11 @@
 ---
-layout: page
-title: About Us
+  layout: default.md
+  title: "About Us"
 ---
 
-We are a team based in the [School of Computing, National University of Singapore](https://www.comp.nus.edu.sg).
+# About Us
+
+We are a team based in the [School of Computing, National University of Singapore](http://www.comp.nus.edu.sg).
 
 You can reach us at the email `seer[at]comp.nus.edu.sg`
 

docs/Configuration.md

@@ -1,6 +1,8 @@
 ---
-layout: page
-title: Configuration guide
+  layout: default.md
+  title: "Configuration guide"
 ---
 
+# Configuration guide
+
 Certain properties of the application can be controlled (e.g user preferences file location, logging level) through the configuration file (default: `config.json`).

docs/DevOps.md

@@ -1,12 +1,15 @@
 ---
-layout: page
-title: DevOps guide
+  layout: default.md
+  title: "DevOps guide"
+  pageNav: 3
 ---
 
-* Table of Contents
-{:toc}
+# DevOps guide
 
---------------------------------------------------------------------------------------------------------------------
+<!-- * Table of Contents -->
+<page-nav-print />
+
+<!-- -------------------------------------------------------------------------------------------------------------------- -->
 
 ## Build automation
 

docs/Documentation.md

@@ -1,29 +1,21 @@
 ---
-layout: page
-title: Documentation guide
+  layout: default.md
+  title: "Documentation guide"
+  pageNav: 3
 ---
 
-**Setting up and maintaining the project website:**
-
-* We use [**Jekyll**](https://jekyllrb.com/) to manage documentation.
-* The `docs/` folder is used for documentation.
-* To learn how set it up and maintain the project website, follow the guide [_[se-edu/guides] **Using Jekyll for project documentation**_](https://se-education.org/guides/tutorials/jekyll.html).
-* Note these points when adapting the documentation to a different project/product:
-  * The 'Site-wide settings' section of the page linked above has information on how to update site-wide elements such as the top navigation bar.
-  * :bulb: In addition to updating content files, you might have to update the config files `docs\_config.yml` and `docs\_sass\minima\_base.scss` (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**_](https://se-education.org/guides/tutorials/intellijUsefulSettings.html#enabling-soft-wrapping)
+# Documentation Guide
 
+* We use [**MarkBind**](https://markbind.org/) to manage documentation.
+* The `docs/` folder contains the source files for the documentation website.
+* To learn how set it up and maintain the project website, follow the guide [[se-edu/guides] Working with Forked MarkBind sites](https://se-education.org/guides/tutorials/markbind-forked-sites.html) for project documentation.
 
 **Style guidance:**
 
 * Follow the [**_Google developer documentation style guide_**](https://developers.google.com/style).
+* Also relevant is the [_se-edu/guides **Markdown coding standard**_](https://se-education.org/guides/conventions/markdown.html).
 
-* Also relevant is the [_[se-edu/guides] **Markdown coding standard**_](https://se-education.org/guides/conventions/markdown.html)
-
-**Diagrams:**
-
-* See the [_[se-edu/guides] **Using PlantUML**_](https://se-education.org/guides/tutorials/plantUml.html)
 
-**Converting a document to the PDF format:**
+**Converting to PDF**
 
-* See the guide [_[se-edu/guides] **Saving web documents as PDF files**_](https://se-education.org/guides/tutorials/savingPdf.html)
+* See the guide [_se-edu/guides **Saving web documents as PDF files**_](https://se-education.org/guides/tutorials/savingPdf.html).

docs/Logging.md

@@ -1,8 +1,10 @@
 ---
-layout: page
-title: Logging guide
+  layout: default.md
+  title: "Logging guide"
 ---
 
+# Logging guide
+
 * We are using `java.util.logging` package for logging.
 * The `LogsCenter` class is used to manage the logging levels and logging destinations.
 *  The `Logger` for a class can be obtained using `LogsCenter.getLogger(Class)` which will log messages according to the specified logging level.

docs/SettingUp.md

@@ -1,27 +1,33 @@
 ---
-layout: page
-title: Setting up and getting started
+  layout: default.md
+  title: "Setting up and getting started"
+  pageNav: 3
 ---
 
-* Table of Contents
-{:toc}
+# Setting up and getting started
 
+<!-- * Table of Contents -->
+<page-nav-print />
 
 --------------------------------------------------------------------------------------------------------------------
 
 ## Setting up the project in your computer
 
-<div markdown="span" class="alert alert-warning">:exclamation: **Caution:**
+<box type="warning" seamless>
 
+**Caution:**
 Follow the steps in the following guide precisely. Things will not work out if you deviate in some steps.
-</div>
+</box>
 
 First, **fork** this repo, and **clone** the fork into your computer.
 
 If you plan to use Intellij IDEA (highly recommended):
+
 1. **Configure the JDK**: Follow the guide [_[se-edu/guides] IDEA: Configuring the JDK_](https://se-education.org/guides/tutorials/intellijJdk.html) to ensure Intellij is configured to use **JDK 17**.
-1. **Import the project as a Gradle project**: Follow the guide [_[se-edu/guides] IDEA: Importing a Gradle project_](https://se-education.org/guides/tutorials/intellijImportGradleProject.html) to import the project into IDEA.<br>
-  :exclamation: Note: Importing a Gradle project is slightly different from importing a normal Java project.
+1. **Import the project as a Gradle project**: Follow the guide [_[se-edu/guides] IDEA: Importing a Gradle project_](https://se-education.org/guides/tutorials/intellijImportGradleProject.html) to import the project into IDEA.
+   <box type="warning" seamless>
+   Note: Importing a Gradle project is slightly different from importing a normal Java project.
+   </box>
 1. **Verify the setup**:
    1. Run the `seedu.address.Main` and try a few commands.
    1. [Run the tests](Testing.md) to ensure they all pass.
@@ -34,10 +40,11 @@ If you plan to use Intellij IDEA (highly recommended):
 
    If using IDEA, follow the guide [_[se-edu/guides] IDEA: Configuring the code style_](https://se-education.org/guides/tutorials/intellijCodeStyle.html) to set up IDEA's coding style to match ours.
 
-   <div markdown="span" class="alert alert-primary">:bulb: **Tip:**
+   <box type="tip" seamless>
 
+   **Tip:**
    Optionally, you can follow the guide [_[se-edu/guides] Using Checkstyle_](https://se-education.org/guides/tutorials/checkstyle.html) to find how to use the CheckStyle within IDEA e.g., to report problems _as_ you write code.
-   </div>
+   </box>
 
 1. **Set up CI**
 

docs/Testing.md

@@ -1,12 +1,15 @@
 ---
-layout: page
-title: Testing guide
+  layout: default.md
+  title: "Testing guide"
+  pageNav: 3
 ---
 
-* Table of Contents
-{:toc}
+# Testing guide
 
---------------------------------------------------------------------------------------------------------------------
+<!-- * Table of Contents -->
+<page-nav-print />
+
+<!-- -------------------------------------------------------------------------------------------------------------------- -->
 
 ## Running tests
 
@@ -19,8 +22,10 @@ There are two ways to run tests.
 * **Method 2: Using Gradle**
   * Open a console and run the command `gradlew clean test` (Mac/Linux: `./gradlew clean test`)
 
-<div markdown="span" class="alert alert-secondary">:link: **Link**: Read [this Gradle Tutorial from the se-edu/guides](https://se-education.org/guides/tutorials/gradle.html) to learn more about using Gradle.
-</div>
+<box type="info" seamless>
+
+**Link**: Read [this Gradle Tutorial from the se-edu/guides](https://se-education.org/guides/tutorials/gradle.html) to learn more about using Gradle.
+</box>
 
 --------------------------------------------------------------------------------------------------------------------
 

docs/UserGuide.md

@@ -1,12 +1,15 @@
 ---
-layout: page
-title: User Guide
+  layout: default.md
+  title: "User Guide"
+  pageNav: 3
 ---
 
-AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized for use via a Command Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, AB3 can get your contact management tasks done faster than traditional GUI apps.
+# AB-3 User Guide
 
-* Table of Contents
-{:toc}
+AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized for use via a  Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, AB3 can get your contact management tasks done faster than traditional GUI apps.
+
+<!-- * Table of Contents -->
+<page-nav-print />
 
 --------------------------------------------------------------------------------------------------------------------
 
@@ -42,9 +45,9 @@ AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized fo
 
 ## Features
 
-<div markdown="block" class="alert alert-info">
+<box type="info" seamless>
 
-**:information_source: Notes about the command format:**<br>
+**Notes about the command format:**<br>
 
 * Words in `UPPER_CASE` are the parameters to be supplied by the user.<br>
   e.g. in `add n/NAME`, `NAME` is a parameter which can be used as `add n/John Doe`.
@@ -62,7 +65,7 @@ AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized fo
   e.g. if the command specifies `help 123`, it will be interpreted as `help`.
 
 * If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines as space characters surrounding line-breaks may be omitted when copied over to the application.
-</div>
+</box>
 
 ### Viewing help : `help`
 
@@ -79,9 +82,10 @@ Adds a person to the address book.
 
 Format: `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​`
 
-<div markdown="span" class="alert alert-primary">:bulb: **Tip:**
-A person can have any number of tags (including 0)
-</div>
+<box type="tip" seamless>
+
+**Tip:** A person can have any number of tags (including 0)
+</box>
 
 Examples:
 * `add n/John Doe p/98765432 e/johnd@example.com a/John street, block 123, #01-01`
@@ -162,10 +166,12 @@ AddressBook data are saved in the hard disk automatically after any command that
 
 AddressBook data are saved automatically as a JSON file `[JAR file location]/data/addressbook.json`. Advanced users are welcome to update data directly by editing that data file.
 
-<div markdown="span" class="alert alert-warning">:exclamation: **Caution:**
-If your changes to the data file makes its format invalid, AddressBook will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.<br>
-Furthermore, certain edits can cause the AddressBook to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.
-</div>
+<box type="warning" seamless>
+
+**Caution:**
+If your changes to the data file makes its format invalid, AddressBook will discard all data and start with an empty data file at the next run.  Hence, it is recommended to take a backup of the file before editing it.<br>
+Furthermore, certain edits can cause the AddressBook to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.
+</box>
 
 ### Archiving data files `[coming in v2.0]`
 
@@ -189,12 +195,12 @@ _Details coming soon ..._
 
 ## Command summary
 
-Action | Format, Examples
---------|------------------
-**Add** | `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​` <br> e.g., `add n/James Ho p/22224444 e/jamesho@example.com a/123, Clementi Rd, 1234665 t/friend t/colleague`
-**Clear** | `clear`
+Action     | Format, Examples
+-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------
+**Add**    | `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​` <br> e.g., `add n/James Ho p/22224444 e/jamesho@example.com a/123, Clementi Rd, 1234665 t/friend t/colleague`
+**Clear**  | `clear`
 **Delete** | `delete INDEX`<br> e.g., `delete 3`
-**Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​`<br> e.g.,`edit 2 n/James Lee e/jameslee@example.com`
-**Find** | `find KEYWORD [MORE_KEYWORDS]`<br> e.g., `find James Jake`
-**List** | `list`
-**Help** | `help`
+**Edit**   | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​`<br> e.g.,`edit 2 n/James Lee e/jameslee@example.com`
+**Find**   | `find KEYWORD [MORE_KEYWORDS]`<br> e.g., `find James Jake`
+**List**   | `list`
+**Help**   | `help`

docs/_markbind/layouts/default.md

@@ -0,0 +1,66 @@
+<head-bottom>
+  <link rel="stylesheet" href="{{baseUrl}}/stylesheets/main.css">
+</head-bottom>
+
+<header sticky>
+  <navbar type="dark">
+    <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand">AB-3</a>
+    <li><a href="{{baseUrl}}/UserGuide.html" class="nav-link">User Guide</a></li>
+    <li><a href="{{baseUrl}}/DeveloperGuide.html" class="nav-link">Developer Guide</a></li>
+    <li><a href="{{baseUrl}}/AboutUs.html" class="nav-link">About Us</a></li>
+    <li><a href="https://github.com/se-edu/addressbook-level3" target="_blank" class="nav-link"><md>:fab-github:</md></a>
+    </li>
+    <li slot="right">
+      <form class="navbar-form">
+        <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback" menu-align-right></searchbar>
+      </form>
+    </li>
+  </navbar>
+</header>
+
+<div id="flex-body">
+  <nav id="site-nav">
+    <div class="site-nav-top">
+      <div class="fw-bold mb-2" style="font-size: 1.25rem;">Site Map</div>
+    </div>
+    <div class="nav-component slim-scroll">
+      <site-nav>
+* [Home]({{ baseUrl }}/index.html)
+* [User Guide]({{ baseUrl }}/UserGuide.html) :expanded:
+  * [Quick Start]({{ baseUrl }}/UserGuide.html#quick-start)
+  * [Features]({{ baseUrl }}/UserGuide.html#features)
+  * [FAQ]({{ baseUrl }}/UserGuide.html#faq)
+  * [Command Summary]({{ baseUrl }}/UserGuide.html#faq)
+* [Developer Guide]({{ baseUrl }}/DeveloperGuide.html) :expanded:
+  * [Acknowledgements]({{ baseUrl }}/DeveloperGuide.html#acknowledgements)
+  * [Setting Up]({{ baseUrl }}/DeveloperGuide.html#setting-up-getting-started)
+  * [Design]({{ baseUrl }}/DeveloperGuide.html#design)
+  * [Implementation]({{ baseUrl }}/DeveloperGuide.html#implementation)
+  * [Documentation, logging, testing, configuration, dev-ops]({{ baseUrl }}/DeveloperGuide.html#documentation-logging-testing-configuration-dev-ops)
+  * [Appendix: Requirements]({{ baseUrl }}/DeveloperGuide.html#appendix-requirements)
+  * [Appendix: Instructions for manual testing]({{ baseUrl }}/DeveloperGuide.html#appendix-instructions-for-manual-testing)
+* Tutorials
+  * [Tracing code]({{ baseUrl }}/tutorials/TracingCode.html)
+  * [Adding a command]({{ baseUrl }}/tutorials/AddRemark.html)
+  * [Removing Fields]({{ baseUrl }}/tutorials/RemovingFields.html)
+* [About Us]({{ baseUrl }}/AboutUs.html)
+      </site-nav>
+    </div>
+  </nav>
+  <div id="content-wrapper">
+    {{ content }}
+  </div>
+  <nav id="page-nav">
+    <div class="nav-component slim-scroll">
+      <page-nav />
+    </div>
+  </nav>
+  <scroll-top-button></scroll-top-button>
+</div>
+
+<footer>
+  <!-- Support MarkBind by including a link to us on your landing page! -->
+  <div class="text-center">
+    <small>[<md>**Powered by**</md> <img src="https://markbind.org/favicon.ico" width="30"> {{MarkBind}}, generated on {{timestamp}}]</small>
+  </div>
+</footer>

docs/_markbind/variables.json

@@ -0,0 +1,3 @@
+{
+    "jsonVariableExample": "Your variables can be defined here as well"
+}

docs/_markbind/variables.md

@@ -0,0 +1,4 @@
+<variable name="example">
+To inject this HTML segment in your markbind files, use {{ example }} where you want to place it.
+More generally, surround the segment's id with double curly braces.
+</variable>

docs/index.md

@@ -1,8 +1,10 @@
 ---
-layout: page
-title: AddressBook Level-3
+  layout: default.md
+  title: ""
 ---
 
+# AddressBook Level-3
+
 [![CI Status](https://github.com/se-edu/addressbook-level3/workflows/Java%20CI/badge.svg)](https://github.com/se-edu/addressbook-level3/actions)
 [![codecov](https://codecov.io/gh/se-edu/addressbook-level3/branch/master/graph/badge.svg)](https://codecov.io/gh/se-edu/addressbook-level3)
 

docs/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "docs",
+  "version": "1.0.0",
+  "description": "AB-3 docs",
+  "scripts": {
+    "init": "markbind init",
+    "build": "markbind build",
+    "serve": "markbind serve",
+    "deploy": "markbind deploy"
+  },
+  "devDependencies": {
+    "markbind-cli": "^5.1.0"
+  }
+}

docs/site.json

@@ -0,0 +1,29 @@
+{
+  "baseUrl": "",
+  "titlePrefix": "",
+  "titleSuffix": "AddressBook Level-3",
+  "faviconPath": "images/SeEduLogo.png",
+  "style": {
+    "codeTheme": "light"
+  },
+  "ignore": [
+    "_markbind/layouts/*",
+    "_markbind/logs/*",
+    "_site/*",
+    "site.json",
+    "*.md",
+    "*.njk",
+    ".git/*",
+    "node_modules/*"
+  ],
+  "pagesExclude": ["node_modules/*"],
+  "pages": [
+    {
+      "glob": ["**/index.md", "**/*.md"]
+    }
+  ],
+  "deploy": {
+    "message": "Site Update."
+  },
+  "timeZone": "Asia/Singapore"
+}

docs/stylesheets/main.css

@@ -0,0 +1,144 @@
+mark {
+  background-color: #ff0;
+  border-radius: 5px;
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
+.indented {
+  padding-left: 20px;
+}
+
+.theme-card img {
+  width: 100%;
+}
+
+/* Scrollbar */
+
+.slim-scroll::-webkit-scrollbar {
+  width: 5px;
+}
+
+.slim-scroll::-webkit-scrollbar-thumb {
+  background: #808080;
+  border-radius: 20px;
+}
+
+.slim-scroll::-webkit-scrollbar-track {
+  background: transparent;
+  border-radius: 20px;
+}
+
+.slim-scroll-blue::-webkit-scrollbar {
+  width: 5px;
+}
+
+.slim-scroll-blue::-webkit-scrollbar-thumb {
+  background: #00b0ef;
+  border-radius: 20px;
+}
+
+.slim-scroll-blue::-webkit-scrollbar-track {
+  background: transparent;
+  border-radius: 20px;
+}
+
+/* Layout containers */
+
+#flex-body {
+  display: flex;
+  flex: 1;
+  align-items: start;
+}
+
+#content-wrapper {
+  flex: 1;
+  margin: 0 auto;
+  min-width: 0;
+  max-width: 1000px;
+  overflow-x: auto;
+  padding: 0.8rem 20px 0 20px;
+  transition: 0.4s;
+  -webkit-transition: 0.4s;
+}
+
+#site-nav,
+#page-nav {
+  display: flex;
+  flex-direction: column;
+  position: sticky;
+  top: var(--sticky-header-height);
+  flex: 0 0 auto;
+  max-width: 300px;
+  max-height: calc(100vh - var(--sticky-header-height));
+  width: 300px;
+}
+
+#site-nav {
+  border-right: 1px solid lightgrey;
+  padding-bottom: 20px;
+  z-index: 999;
+}
+
+.site-nav-top {
+  margin: 0.8rem 0;
+  padding: 0 12px 12px 12px;
+}
+
+.nav-component {
+  overflow-y: auto;
+}
+
+#page-nav {
+  border-left: 1px solid lightgrey;
+}
+
+@media screen and (max-width: 1299.98px) {
+  #page-nav {
+    display: none;
+  }
+}
+
+/* Bootstrap medium(md) responsive breakpoint */
+@media screen and (max-width: 991.98px) {
+  #site-nav {
+    display: none;
+  }
+}
+
+/* Bootstrap small(sm) responsive breakpoint */
+@media (max-width: 767.98px) {
+  .indented {
+    padding-left: 10px;
+  }
+
+  #content-wrapper {
+    padding: 0 10px;
+  }
+}
+
+/* Bootstrap extra small(xs) responsive breakpoint */
+@media screen and (max-width: 575.98px) {
+  #site-nav {
+    display: none;
+  }
+}
+
+/* Hide site navigation when printing */
+@media print {
+  #site-nav {
+    display: none;
+  }
+
+  #page-nav {
+    display: none;
+  }
+}
+
+h2,
+h3,
+h4,
+h5,
+h6 {
+  color: #e46c0a;
+}

docs/team/johndoe.md

@@ -1,6 +1,6 @@
 ---
-layout: page
-title: John Doe's Project Portfolio Page
+  layout: default.md
+  title: "John Doe's Project Portfolio Page"
 ---
 
 ### Project: AddressBook Level 3