Contributing to The ZIO Documentation

The ZIO documentation is provided by a worldwide community, just like the project itself. So if you are reading this page, you can help us improve the documentation.

Please read the Contributor Guideline before contributing to documentation.

Toolchain

1. The documentation is written in Markdown format.
2. During the build process of the microsite, we use mdoc to type-check code snippets in Markdown.
3. Our site generator is Docusaurus.

Editing with GitHub Editor

We encourage contributors to use GitHub's editor for making minor changes to existing documents.

1. On each page, there is a button called Edit this page. By clicking this button, we will be redirected to the GitHub editor.

   

2. After editing the page, we can check whether our changes have been formatted correctly by using the Preview tab.

   

3. We can scroll to the bottom of the page, write a title and description of the work, and then propose the changes by clicking on Propose changes.

   

4. Our browser will be redirected to a new page titled Comparing changes after clicking the Propose changes button. We can compare our proposed changes and then create a pull request by clicking the Create pull request button.

   

5. On the new page, we can edit the title and description of our pull request and finally click Create pull request.

   

6. A pull request has been created. Eventually, our work will be reviewed by the rest of the team.

Editing Documentation Locally

ZIO contributors are encouraged to use this approach for introducing new documentation pages, or when we have many improvements to code snippets, since we can compile-check all changes locally before committing and sending a pull request to the project:

1. First, we need to fork and clone the ZIO project on our machine. Follow the Get The Project instructions to fork the repository and clone your fork.

2. The documentation source files can be found in the docs directory, and they are all in Markdown format. Now we can begin improving the existing documentation or adding new documentation.

3. To generate the documentation site from type-checked Markdown files, we can use the following command:

   sbt docs/mdoc

   If one of our code snippets fails to compile, this command will not succeed and will indicate which line of the documentation caused the error.

   It is recommended to run this command in the sbt shell with the --watch option. This will start a file watcher and live-reload on changes. It is useful when we want to see the intermediate results while we are writing documentation:

   sbt
   sbt:docs> docs/mdoc --watch

4. Finally, we can serve the microsite locally with the following command:

   cd website
   npm install
   npm run start --watch

   It will be served at the localhost address.

5. When we are finished with the documentation, we can commit those changes and create a pull request.

AI-friendly Markdown Variants

The website publishes /llms.txt and /llms-full.txt at the site root (per the llmstxt.org standard) so LLMs and AI agents can discover and ingest the documentation without scraping HTML. It also serves a Markdown variant next to every documentation page — for example, the page rendered at /reference/schedule/ is also available as plain Markdown at /reference/schedule.md.

Two pieces cooperate to produce this:

1. The docusaurus-plugin-llms plugin generates llms.txt, llms-full.txt, and a .md variant for every documentation source file. Its configuration lives in website/docusaurus.config.js.
2. A small post-build script, website/scripts/llms-md-mirror.js, runs after docusaurus build (from the build entry in website/package.json) and mirrors the generated Markdown to match the canonical page URL.

The mirror step exists because docusaurus-plugin-llms writes each .md at the source file path, while Docusaurus renders HTML at a different path in two common cases:

• reference/schedule/index.md is rendered at /reference/schedule/, so the natural Markdown URL is /reference/schedule.md, not /reference/schedule/index.md.
• reference/core/zio/zio.md is rendered at /reference/core/zio/ (Docusaurus's folder-named-doc convention), so the natural Markdown URL is /reference/core/zio.md.

The script scans the build output and, for every <dir>/index.md or <dir>/<dir>.md it finds, creates a sibling <dir>.md so that appending .md to any rendered URL resolves. It never overwrites an existing file, so its output composes cleanly with the llms plugin and with any future upstream fix. Running after docusaurus build (rather than as another Docusaurus plugin) avoids racing against the llms plugin — Docusaurus runs plugins' postBuild hooks concurrently, so a mirror plugin could walk the build directory before the llms plugin had finished writing its .md files. This keeps the solution in one place rather than requiring explicit slug: frontmatter on every index and folder-named-doc file across the site and the ~30 ecosystem subprojects synced in from npm.

Giving Feedback

Sometimes we see a problem in the documentation, or we have an idea to improve it, but we don't have the time or knowledge to do it ourselves. We can discuss those ideas with the community. There are two ways to do this:

1. Using Discord (https://discord.gg/2ccFBr4) is a great way to share our thoughts with others, discuss them, and brainstorm big ideas.
2. Opening a new issue (https://github.com/zio/zio/issues/new) is appropriate when we have actionable ideas, such as reorganizing a specific documentation page or reporting a problem with the current documentation.

See Also

• Coding Guidelines — Style and conventions for writing ZIO code, relevant when adding code examples to documentation