Writing documentation

Terracore’s documentation is written with Starlight, a documentation framework based on Astro. Documentation pages are authored in MDX or Markdown.

Note

The documentation on this page is hyper-focused on getting you started writing documentation for Terracore. For complete documentation on MDX, Starlight, Astro or their plugins, checkout their respective websites.

Documentation structure

All of Terracore’s documentation lives in its Git repository’s docs/ subdirectory.

• Directorybukkit/

  • …
• Directorydocs Root of the documentation

  • Directorypublic/ Public assets (not processed by Astro)

    • …
  • Directorysrc

    • Directoryassets/ Public assets (processed by Astro)

      • …
    • Directorycomponents/ Custom Astro components

      • …
    • Directorycontent

      • Directorydocs Where the real content of the site lives

        • Directorycontributing

          • docs.mdx The very page you are reading
          • …
        • Directorygeo/ Pages for the geo module

          • …
        • Directoryhttp/ Pages for the HTTP module

          • …
        • Directoryminecraft/ Pages for the minecraft module

          • …
        • Directorystart/ Help to get started using Terracore

          • …
        • Directoryworldgen/ Pages for the worldgen module

          • …
        • index.mdx Welcome page of the site
    • content.config.ts
  • astro.config.mjs
  • package.json
  • package-lock.json
  • README.md
  • tsconfig.json
  • …
• Directorygeo/

  • …
• Directorygradle/

  • …
• Directoryhttp/

  • …
• Directoryminecraft/

  • …
• Directoryworldgen/

  • …
• build.gradle.kts
• LICENSE.md
• README.md
• settings.gradle.kts
• …

Note

Astro has a dedicated page on project structure.

Running the development server

Tip

The following instructions assume you start from 0, feel free to skip steps if you already have things setup.

1. Make sure you have NodeJS and Git installed and working on your computer.

2. Make sure you have a local copy of the repository and move to the docs/ subdirectory.

   git clone git@github.com:BTE-France/terracore.git
   cd terracore/docs

3. Install the Node packages needed to run the server.

   npm install

4. Run the dev server and open the displayed URL in your browser. You can now edit the Terracore documentation and see your changes in your browser.

   npm run dev

   Tip

   Previous steps only need to be ran once, jump straight to this one when returning to an existing project.

Writing

Simply start the development server and start modifying the files in the content/ directory.

Reading the following to Starlight documentation pages to learn about the available syntax:

• Authoring content in Markdown
• Using components, and everything under the “Components” section

Configuring versions of the documentation published on GitHub pages

The documentation is published over at https://terracore.btefrance.fr via a GitHub Actions workflow. It can bundle different versions of the docs and publish them all together. Edit the SITE_VERSIONS variable in the docs-deploy.yml workflow file to control which versions are included.