Developer Documentation Server

Originally most of the developer documentation was contained within the Github repository's wiki. However, as the documentation became more comprehensive in scope and complex in design, it was necessary to migrate to a more advanced and configurable solution.

This documentation server is powered by Vitepress, which takes Markdown files and renders them into a (mostly) static site.

Base URL

The entire developer documentation server is designed to be deployed at , which means that all links throughout the docserver's source code will be calculated relative to this URL. This setting is controlled by the base option in the Vitepress config file.

Directory Structure

All pages for the server are contained under src.

vitepress-sidebar is being used to generate the sidebar for the server. This means that entries in the sidebar appear sorted according to the file/folder names from which they originate. This is why some folder have contents that are labelled 1-something, 2-something etc. Each item's value is taken from file's frontmatter, or if not present, the file's first header.

If there is a file with the same name as its parent folder, then that file is used as the target for the path. For example:

1-bundles
├── 1-bundles.md
└── example.png   // Picture that's displayed in 1-bundles.md

then the link ./1-bundles.html will automatically display the 1-bundles.md page. Using a folder this way lets you group assets intended for a single page.

If instead you use an index.md page, then the the sidebar displays a menu group, the title of which is taken from the index.md page. For example:

bundles
├── index.md
├── 1-getting-started
│   ├── 1-overview.md
│   ├── 2-start.md
│   ├── 3-cheat.md
│   ├── 4-faq.md
│   └── index.md
└── 2-bundle
    ├── 1-overview
    │   └── 1-overview.md
    ├── 2-creating.md
    │   └── 2-creating.md
    ├── 3-editing.md
    ├── 4-documentation
    │   └── 4-documentation.md
    ├── 5-type_map.md
    ├── 6-compiling.md
    └── index.md

The above file structure produces the menu below:

Each page can then be referred to using ./bundles/1-getting-started/1-overview.html or ./bundles/2-bundle/1-overview.html etc.

Each item takes its title value from either the frontmatter (if available) or the first heading of each page.

index.md files are only used to title the menus, they are not intended for navigation, though are navigable to if the user enters the address manually, so it is still recommended to keep some basic documentation in those pages or create rewrites so that users are automatically redirected away from those pages. Here are the contents of :

---
title: Bundles
---

Table of Contents:

1. [Overview](./1-overview/1-overview)
2. [Creation](./2-creating/2-creating)
3. [Editing](./3-editing)
4. [Conventions](./4-conventions/1-basic)
5. [Documentation](./5-documentation/1-cadet/1-cadet.md)
6. [Compilation](./6-compiling)
7. [Type Maps](./7-type_map)

Instead, the links in the sidebar link to the page (if it is a markdown file), or to a child within the folder that has the same name as that folder.

Documentation for modules-lib

The documentation for @sourceacademy/modules-lib is automatically generated by Typedoc. The configuration options for this generation are found in that folder. The documentation for @sourceacademy/modules-lib should be built before this server is built.

help pls

Supposedly Vitepress can embed React components, which would be nice for us to have working demonstrations of our React components. Unfortunately, I have never been able to get that to work. You can start here if you want to help figure this out.

Diagrams

Diagrams (such as the one seen here) are supported via the mermaid rendering engine and provided with the Vitepress plugin for mermaid. Simply use a Markdown code block with the mermaid language tag.

Code Snippets

vitepress provides the ability for a Markdown document to "import" a code snippet from an external file. This function is documented here.

Throughout many files in the repository, you will see VSCode #region comments. These comments are used to mark out a VSCode region in Typescript/Javascript and are used by the doc server to extract only a specified portion of the code within the file. Do not remove these comments unless absolutely necessary.

Tree Diagrams

Directory tree diagrams like the one below

this
├── is
├── a
└── tree
    └── diagram

are generated via their own markdown plugin, the details of which can be found here.

Production Build and Dead Links

The preview version of the docs rendered by Vitepress when the vitepress dev command is executed is not the final version that is intended to be displayed. For this, Vitepress provides the vitepress build command, which converts the documentation source into its final, minified HTML form.

As part of this process, Vitepress will highlight any "dead" links (i.e links that don't point to anything) and will fail if it finds any. If you're editing the documentation, you should run the build command to check for the dead links before pushing to the repository.