Maia Documentation

Appearance

Getting Started ​

Introduction ​

The Maia documentation depends on two libraries:

  1. VitePress
    • ...a Static Site Generator (SSG) which takes source markdown, applies a theme and generates static HTML.
  2. TypeDoc
    • ...converts comments in TypeScript into HTML documentation.

A markdown plugin (typedoc-plugin-markdown) enables comment-generated output HTML to be generated as markdown files and themed for VitePress.

TypeDoc must be added to each front end project, see below.

Run Locally ​

To run the documentation locally:

powershell
cd ./docs # if not already
pnpm install
pnpm dev

Project will open at http://localhost:5179/.

Add typedoc to a Project ​

  1. Install typedoc with the markdown and theme plugins:

    powershell
    cd <project>
pnpm add typedoc typedoc-plugin-markdown typedoc-vitepress-theme --save-dev

  2. Add a typedoc.json file and add:

    json
    {
  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
  "out": "../docs/<my-project>"
}

    Where <my-project> is the location of your documents in the documentation hierarchy.

    TIP

    Note that a typedoc-sidebar.json file will be created at this location, which will help to configure navigation.

    WARNING

    Ensure that the out property points to the documentation folder (.\doc in the root of the i-Coach Maia project).

  3. Add a gendoc to packages.json, to run the document generator.

    json
    "scripts": {
    "dev": "vite",
    "build": "tsc -b ./tsconfig.lib.json && vite build",
    ...
    "gendoc": "typedoc"
  },

  4. In the .\docs project folder, tell the navigation about your new content (.\docs\.vitepress\config.mts):

    ts
    import myProjectSidebar from "../api/typedoc-sidebar.json";

module.exports = {
  themeConfig: {
    nav: [{ text: "My Project", link: "/my-project/" }], // items for the top nav bar

    sidebar: [
      // items for the left menu panel
      {
        text: "My Project",
        items: myProjectSidebar,
      },
    ],
  },
};

  5. Once the projects are initialised, you will need to run pnpm gendoc to generate the markdown files from your project's comments.

    If you have a README.md, it will be picked up as the index.md for your project documentation.

    View your changes (see Run Locally) 🥳 😀

  6. Commit and push the changes to your branch. Merge into main branch. DONE.

WARNING

It is important to run a build pnpm build and a preview pnpm preview within the .\docs folder to ensure the build will succeed on the pipeline. Depending on confuguration, even dead links will fail the build...

Deployment ​

The CI folder in the i-Coach Maia project contains a pipeline to deploy the documentation to an Azure static web app.