Skip to content

Add documentation site - #11

Open
leslieyip02 wants to merge 3 commits into
masterfrom
docs/github-pages-docs
Open

Add documentation site#11
leslieyip02 wants to merge 3 commits into
masterfrom
docs/github-pages-docs

Conversation

@leslieyip02

@leslieyip02 leslieyip02 commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Currently, there are 2 sources of documentation:

  1. The docs/ folder contains markdown files
  2. ./gradlew dokkaHtml can be used to generate Kotlin API documentation

This PR combines both into a static site, which can be deployed via GitHub Pages.

Static Site Generation

I added MkDocs with Material for MkDocs to generate static HTML content from the markdown in the docs/ folder.
The commands are all grouped together, and serving the site locally is as simple as:

# Assuming you have python3 installed somewhere
./scripts/build_docs.sh
./scripts/serve_docs.sh

The end result looks like this:

Screenshot 2026-09-05 at 10 35 02 AM Screenshot 2026-09-05 at 10 35 22 AM

The Kotlin API docs can also be accessed at /api:

Screenshot 2026-09-05 at 10 35 10 AM

Note: I moved the docs/Module.md file used by Dokka into dokka/module.md so that docs/ is purely MkDocs content.

I feel that having a static site improves the docs reading experience, and also allows more customization. For example, we can add notes, warnings, TODOs, and collapsible sections.

GitHub Actions

I've added a workflow to host the docs site on GitHub Pages. To set this up, go to Settings > Pages and set the "Build and deployment" source to GitHub Actions.

Screenshot 2026-09-05 at 3 33 46 PM

Since I don't have repo permissions, I created a fork to test the GitHub Actions as well: https://leslieyip02.github.io/jade/ (the content here is different, I just deployed it test the workflow).

Content Cleanups

I tried to clean up the docs as much as I can, and I grouped them as follows:

nav:
  - Home: index.md
  - User Guide:
      - Overview: user-guide/overview.md
      - Commands: user-guide/commands.md
  - Developer Guide:
      - Overview: developer-guide/overview.md
      - Algorithms: developer-guide/algorithms.md
      - Commands: developer-guide/commands.md
      - Style Guide: developer-guide/style.md
  - Testing:
      - Overview: testing/overview.md
      - Maven Development: testing/maven.md
  - Internal:
      - Roadmap: internal/roadmap.md
      - Notes: internal/notes.md
      - Links: internal/links.md
      - Archive: internal/archive.md

That said, there's a lot of confusing / outdated docs so I dumped everything I wasn't sure about into archive.md.

Consolidates documentation from 2 sources:

1. Markdown files in docs/ with MkDocs
2. Kotlin API docs with Dokka
Moved Dokka's module.md into a standalone dokka/ directory since the
docs/ directory is used for MkDocs.
- Grouped markdown files into folders
- Cleaned up command documentation
- Update README
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant