Documentation

We appreciate your interest in improving NAHPU documentation. Several ways you can help:

• Update existing docs: Fix errors or add new information to current pages
• Create new content: Write new pages or sections on topics we haven't covered yet
• Translate docs: Help us reach more people by translating into other languages (coming soon)

Updating Existing Docs

Team Members

At the bottom of each page on the website, you will find an Edit page link. Click on this link to open the page in GitHub. Here's the step to do it:

1. Check if you have been added as a collaborator.

   Go to GitHub repository and navigate to Settings → Collaborators. If you do not see your username listed, reach out to a NAHPU team member to request access.

2. Click the Edit page link at the bottom of the page.

   This will open the file directly in the GitHub web editor.

3. Start by making small changes.

   If you are new to the project, begin with minor fixes such as typos, grammar corrections, or broken links before tackling larger edits.

4. Commit your changes.

   GitHub will prompt you to write a commit message. Keep it concise, descriptive, and start with an active verb. Example of a good message:

   Fix typos in the mammalian measurements.

5. Select a commit option.

   • Commit directly to the release branch — preferred if you have collaborator access and the change is minor.
   • Create a new branch and open a pull request — use this if direct commit fails or if your change is significant and needs review.

6. Check your changes.

   After committing, navigate to the Actions tab in the GitHub repository to monitor the build. Wait for the workflow to complete. A green checkmark indicates a successful deployment. Once the build is done, visit the page where you made your changes on the live site to verify everything looks correct.

7. Make more changes.

   Repeat steps 2–5 for any additional edits. For larger contributions involving multiple pages or new sections, consider cloning the repository locally for a more efficient workflow.

   We use Markdoc format for our documentation. This format is similar to markdown but with additional features for documentation. It is designed to be easy for non-technical contributors to contribute while providing flexibility to style the writing.

   Consider the following when making changes:

   • Any text enclosed with {% text %} is a Starlight component. It is sensitive to spaces.
   • You can use the component to style your writing. Learn more below.

8. Continue with step 4 and 5.

External Contributors

If you are not a team member, you can still contribute to the project. Here's how:

1. Fork the documentation repository on GitHub, then clone it to your local machine.

   Git

   git clone https://github.com/nahpu/nahpu-docs.git

   GitHub CLI

   gh repo clone nahpu/nahpu-docs

2. Navigate into the project directory.

   cd nahpu-docs

3. Create a new branch for your changes.

   git checkout -b your-branch-name

4. Make your changes to the documentation.

   Files are located in src/content/docs/[language].

5. Commit and push your changes.

   git add .
   git commit -m "Your commit message"
   git push origin your-branch-name

6. Submit a pull request.

   Go to the GitHub repository and open a pull request from your branch. A maintainer will review and merge your changes before the site is deployed.

Did you know?

NAHPU always welcomes new contributors! We are a mix of technical and non-technical contributors. Please reach out to a NAHPU team member for more details.

Create New Content

For create one or two pages, you can add a new file in the GitHub repository. The documentation files are inside src/content/docs/[language]. We need to add the English content first, then write translations for the other languages. We prefer the documentation in markdoc .mdoc format. However, you can start with plain Markdown and let the documentation maintainer do the rest.

For a more complex scenario with complex pages and rooting, see the Deep Dive section for more details.

Adding a New Language Translation

We're always looking for speakers of languages we don't currently support. To facilitate the addition of new languages, we use AI to assist with translations. If you're interested in contributing, please reach out to one of our team members. Our workflow for adding a new language involves:

1. Creating a new language directory in the src/content/docs folder. The folder name follows the language code (e.g., en, es, fr).
2. Using a large language model to translate the English documentation.
3. Add the sidebar translations in the astro.config.mjs file.
4. Reviewing and revising the AI translation for accuracy by a team member.

Deep Dive

This section explains the advanced method to develop the NAHPU documentation.

Technologies

NAHPU documentation is built with the following technologies:

• Astro — Static site generator
• Starlight — Documentation theme for Astro
• Markdoc — Documentation format
• Tailwind CSS — Utility-first CSS framework
• Bun — JavaScript runtime and package manager

Why These Technologies?

Astro generates static HTML pages at build time, meaning the documentation site ships zero JavaScript by default. This results in fast page loads, low bandwidth usage, and a smaller carbon footprint. They are important values for the NAHPU project.

Starlight is Astro's official documentation theme. It provides out-of-the-box features essential for technical documentation, including full-text search, sidebar navigation, internationalization, and accessibility, without requiring us to build them from scratch.

Markdoc extends standard Markdown with a powerful, structured tag system. Unlike MDX, Markdoc keeps content and logic cleanly separated, making it easier for non-technical contributors to write and edit documentation without worrying about breaking component code. It also validates content at build time, catching errors early.

Tailwind CSS allows us to style custom pages and components using utility classes directly in markup, without writing separate CSS files. Its design token system ensures visual consistency across pages, and its built-in purging keeps the final stylesheet small.

Bun is a fast JavaScript runtime and package manager that replaces Node.js and npm in our development workflow. It is less finicky than Node.js and npm, and it installs dependencies significantly faster. It also runs build scripts with lower overhead, making local development and CI builds quicker for contributors.

Local Development

Prerequisites

Before setting up the documentation locally, make sure you have the following installed:

• Git
• Bun
• GitHub CLI (optional, but recommended)
• A code editor (e.g., VS Code)

Experienced Git user?

If you already have Git configured and connected to GitHub, skip to step 5 to install Bun and set up the documentation locally.

1. Install Git.

   macOS

   Git comes pre-installed on macOS. Verify with:

   git --version

   If not installed, install it via Homebrew:

   brew install git

   Linux

   # Debian/Ubuntu
   sudo apt install git
   
   # Fedora
   sudo dnf install git

   Windows

   Download and install Git from git-scm.com. During installation, keep the default options. Verify with:

   git --version

2. Install GitHub CLI (optional, but recommended).

   macOS

   brew install gh

   Linux

   # Debian/Ubuntu
   sudo apt install gh
   
   # Fedora
   sudo dnf install gh

   Windows

   winget install --id GitHub.cli

   Verify the installation:

   gh --version

3. Authenticate GitHub CLI with your GitHub account.

   gh auth login

   Follow the prompts: select GitHub.com as the host, HTTPS as the protocol, and confirm when asked to authenticate via browser. Verify once complete:

   gh auth status

4. Configure Git with your name and email.

   git config --global user.name "Your Name"
   git config --global user.email "your@email.com"

   Use the same email address associated with your GitHub account.

5. Install Bun.

   macOS / Linux

   curl -fsSL https://bun.com/install | bash

   Windows

   powershell -c "irm bun.sh/install.ps1 | iex"

   Verify the installation:

   bun --version

6. Clone the documentation repository.

   Git

   git clone https://github.com/nahpu/nahpu-docs.git

   GitHub CLI

   gh repo clone nahpu/nahpu-docs

7. Navigate into the repository.

   macOS / Linux

   cd nahpu-docs

   Windows

   # PowerShell 7+
   cd nahpu-docs
   
   # Alternatively, use the full cmdlet
   Set-Location nahpu-docs

   If you are using VS Code, you can open it directly in the editor.

   code nahpu-docs

8. Install all dependencies.

   bun install

9. Make your changes.

   Documentation files are in src/content/docs/[language]. Other pages are in src/pages.

Directory structure

Here's the directory structure and short description of each file/directory.

• astro.config.mjs Configuration for Astro site
• markdoc.config.mjs Configuration for Markdoc documentation
• package.json Project dependencies and scripts
• README.md Overview and instructions for the project
• tsconfig.json TypeScript configuration
• Directorypublic/ Static assets served directly

  • …
• Directorysrc/ Main source code directory

  • content.config.ts Content management configurationS
  • Directoryassets/ Media files like images

    • …
  • Directorycomponents/ Reusable UI components

    • …
  • Directorycontent/ Documentation files organized by language

    • …
  • Directorylayouts/ Layout components for reusable page template

    • …
  • Directorypages/ Main pages of the site

    • …
  • Directorystyles/ Global CSS stylesheets

    • …

For more details about the directory structure, follow Astro guidelines and Starlight documentation.

---

Code Conventions

Markdoc Documentation Files

Most contributors will work on .mdoc files inside src/content/docs/[language]. Follow these conventions when editing or creating documentation pages:

1. Use Markdoc syntax for all documentation files. Prefer .mdoc over plain .md to take full advantage of custom tags and components.

2. Use built-in Starlight components for common UI patterns such as asides, steps, tabs, and file trees. See Writing with Starlight Components for examples.

3. Keep frontmatter minimal. Only include fields required by the schema, such as title and sidebar:

   ---
   title: "Page Title"
   sidebar:
     order: 1
   ---

Astro and General Pages

These conventions apply to .astro files in src/components/, src/layouts/, and src/pages/:

1. If the same code snippet appears in multiple places, use a shared component to avoid duplication. Place shared components in src/components/ using PascalCase filenames, e.g., SharedComponent.astro.

2. Use layouts for reusable UI templates. Follow the same PascalCase naming convention and place them in src/layouts/.

3. Avoid vanilla CSS for styling whenever possible. Use Tailwind CSS instead. We use Tailwind v4.

4. Avoid writing many classes inline on elements. Instead, use a cntl const variable to store classes. See src/pages/index.astro for an example.

Danger

Tailwind CSS usage outside the docs directory requires importing global styles: import "../styles/global.css". See src/pages/index.astro for an example.

Writing with Starlight Components

When writing documentation, keep the following in mind:

• Use Starlight components for repeated documentation patterns.
• Use the code component whenever you need to show Markdoc component syntax as text.
• Keep examples short and easy to copy.
• Prefer examples that match the NAHPU documentation workflow.

Built-in Components

You can include a tip box in your documentation using the aside component:

{% aside type='tip' %}
This is a tip!
{% /aside %}

It will render as:

Tip

This is a tip!

For showing numbered steps, you can use the steps component:

{% steps %}
1. Step one
2. Step two
{% /steps %}

It will render as:

1. Step one
2. Step two

You can find the full list of Starlight components in the Starlight documentation.

Adding New Components

1. Create a new component in src/components/. Use PascalCase for the filename, e.g., MyComponent.astro.

   src/components/MyComponent.astro

   <div>
     Your component content here
   </div>

2. Register it as a Markdoc tag in markdoc.config.mjs.

   import { defineMarkdocConfig, component } from "@astrojs/markdoc/config";
   import starlightMarkdoc from "@astrojs/starlight-markdoc";
   
   export default defineMarkdocConfig({
     extends: [starlightMarkdoc()],
     tags: {
       mycomponent: {
         render: component("./src/components/MyComponent.astro"),
         selfClosing: true,
       },
     },
   });

3. Use it in any .mdoc file.

   {% mycomponent / %}

Self-closing vs. block tags

Use selfClosing: true for components that don't wrap content. For components that wrap content, omit it and use opening and closing tags:

{% mycomponent %}
  Content goes here
{% /mycomponent %}

Running the website locally

1. Run astro in dev mode

   bun run dev

2. Open your browser and navigate to http://localhost:4321/ to view the documentation website.

   Tip

   In VS Code, you can CTR + click the link shown in the terminal.