Gukhanmun documentation
=======================

This directory contains the [Rspress] documentation site for Gukhanmun.
The site is built from Markdown and MDX source files and uses TypeDoc to
generate the API reference.

[Rspress]: https://rspress.dev/


Development
-----------

Start the local dev server from the workspace root (builds all required
packages first):

~~~~ sh
mise run docs-dev
~~~~

The dev server hot-reloads on file changes.


Production build
----------------

Build the static site for deployment:

~~~~ sh
mise run docs-build
~~~~

The output lands in *doc\_build/*.


Preview
-------

To preview the production build locally, run from this directory:

~~~~ sh
pnpm run preview
~~~~


Structure
---------

 -  *guide/* contains hand-written user-facing documentation, organised into
    three subdirectories: *cli/*, *javascript/*, and *rust/*.
 -  *internals/* contains design and implementation notes.  *design.md* is a
    symlink to *DESIGN.en.md* at the workspace root.
 -  *api/* holds the API reference.  *api/js/* is auto-generated by TypeDoc
    and must not be edited by hand.
 -  *index.md* is the landing page.


Editing
-------

To add a new page, create a *.md* or *.mdx* file in the appropriate
subdirectory and include a `description` frontmatter field for SEO:

~~~~ md
---
title: Page title
description: One-sentence summary of this page.
---
~~~~

After editing any Markdown file, format it with `hongdown`:

~~~~ sh
hongdown -w path/to/file.md
~~~~

When linking from one documentation page to another, use a relative path that
ends in the *.md* or *.mdx* extension, optionally followed by an anchor:

~~~~ md
See [building a custom dictionary](../cli/dictionary.md#building-a-custom-dictionary).
~~~~

Rspress resolves these to the right route, and the explicit extension keeps the
anchor intact through `hongdown`.

For prose conventions (sentence case, em dash avoidance, italics for paths,
etc.), see the *Writing docs* section of
[*CONTRIBUTING.md*](../CONTRIBUTING.md).