SA Modules

Appearance

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.

File 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.

Folders produce item groups, the name of which can be customized using an index.md file within that folder.

dirtree
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: image

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 :

md
---
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

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

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

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.