Drasi documentation

This repo contains the documentation source for https://drasi.io.

Contributing

Follow the guidance in this file to learn how to contribute to Drasi's documentation.

Please review our Contributions guide prior to making contributions.

Drasi's documentation follows the Diataxis framework for its structure and content.

The documentation website is generated with the Hugo framework.

The documentation website uses the Docsy theme. Refer to the Docsy authoring guide for helpful tips on creating content.

Building the docs

You can use the pre-configured dev container for this repository in Visual Studio Code or GitHub Codespaces.

Alternatively, you can follow the instructions below to setup and run a local Hugo server to edit and view your changes.

Pre-requisites

• Hugo extended
• Go (required for Hugo modules)
• Node.js

Setup Hugo and Docsy

1. Clone the drasi-project/docs repo

2. The Docsy theme is configured as a submodule which needs to be pulled. From the root of the drasi-project/docs repo (where this readme is located) run:

   git submodule update --init --recursive

3. Switch to the Docsy theme folder:

   cd docs/themes/docsy

4. Build the Docsy theme by running:

   npm install

Drasi Server tutorials module workflow

The Drasi Server tutorials are sourced from github.com/drasi-project/learning-drasi-server via Hugo modules, pinned in docs/go.mod.

• Update to the latest published module version:

  make update-tutorials
  

• Update to a specific version:

  make update-tutorials VERSION=v0.1.1
  

After updating, commit docs/go.mod and docs/go.sum.

Preview docs against a local learning-drasi-server checkout

Use this when testing tutorial changes before creating/tagging a module release.

• If your local checkout is at ../learning-drasi-server:

  make preview-docs
  

• If your checkout is elsewhere, pass the path explicitly:

  make preview-docs TUTORIALS_LOCAL=/absolute/path/to/learning-drasi-server
  

Run the Hugo server

1. Ensure you are in the docs folder of the drasi-project/docs repo.

2. Run:

   hugo server --disableFastRender

   Note: If the server takes a long time to start and http://localhost:1313/ shows no content until it finishes, you are likely running from a networked or external/mounted volume where Hugo's native file watching is slow to set up. Add the --poll flag to use polling instead:

   hugo server --disableFastRender --poll 700ms

Browse the documentation

The documentation website will be accessible on the URL http://localhost:1313/

Code of Conduct

Please refer to Drasi's Community Code of Conduct.