Contribute to Temporal Documentation Locally

August 7, 2026 · View on GitHub

  1. Fork the Repository Create a fork of this repository. This creates a copy of this repository to your github account

  2. Clone the Repository
    Run the following commands in your terminal to clone the repository and navigate into it:

    git clone https://github.com/YOUR_USERNAME/documentation.git
cd documentation

  3. Open the Repository in Your IDE
    Open the project in your preferred IDE, such as Visual Studio Code. Locate the /docs directory, which contains all the content served on docs.temporal.io. Identify the changes you want to make.

  4. Create a New Branch
    If you're creating a pull request, create a new branch and switch to it:

    git checkout -b my-documentation-contribution

  5. Understand the docs architecture and follow the style guide
    Refer to INFORMATION-ARCHITECTURE.md to understand where content belongs and what form it should take. Refer to STYLE.md for the documentation style guidelines.

  6. Preview Your Changes Locally
    Run the following commands to preview the site locally:

    yarn            # Install site dependencies
yarn start      # Start the website on a local port
yarn build      # Check for build warnings or errors

  7. Stage Your Changes
    Use the following commands to stage and commit your changes:

    git status                         # Check the status of your changes
git add <file-name>                # Stage files individually
git commit -m "Documentation Change"           # Commit your changes
git push origin my-documentation-contribution  # Push changes

  8. Create a Pull Request

    • After pushing, GitHub provides a link in the terminal to create a PR. Open the link or navigate to your fork on GitHub.
    • Click the option to create a Pull Request (PR).
    • Provide a descriptive PR title and explanation.
    • Submit the PR and wait for feedback.

Contributing Through the GitHub UI

For small changes like fixing typos, you can edit files directly on GitHub.

  1. Open the Temporal Docs Repository

    Go to temporalio/documentation.

  2. Find and Edit the File

    Navigate to the file, click its name, and use the pencil icon to make edits.

  3. Commit Your Changes

    Add a brief commit message, create a new branch (e.g., fix-typo), and commit your changes.

  4. Create a Pull Request (PR)

    Follow GitHub’s prompt to open a PR. Add a clear title and description.

  5. Verify and Tag

    Verify your changes and tag as community-contribution.

  6. Wait for Feedback

    Once approved, your change goes live! 🎉

Maintainers and contributors to this project are expected to conduct themselves in a respectful way. See the CNCF Community Code of Conduct as a reference.

This repository and its contents are open-source; individual and commercial use are permitted.

MIT License

File a Github Issue

If you aren't part of the temporalio organization, you may also file a Github issue as part of your change request.

Sign the CLA

When you submit a Pull Request for the first time, you will be prompted to sign a CLA. Please sign this ASAP. We won't be able to merge in your changes unless you sign the Contributor License Agreement.

Style guidance

See STYLE.md for style guidance.

Preview changes

You can preview how your changes will appear on the website locally on your machine.

Make sure you have Yarn and Node.js installed. Make sure you install the latest version of Node.js (later than 24.0.0).

Run yarn to install the site dependencies.

Run yarn start to start the website on local port.

Run yarn build to see if there are any build warnings or errors.

Automatic formatting

Use yarn format to format changes automatically.

Broken links

hyperlink is a command-line tool to find broken links.

In a terminal, run:

yarn check-links

This command will start the hyperlink checker.

Snipsync

This repository is configured for Snipsync, which checks in the snippets included throughout our documentation.

The reason we use Snipsync is because this repo does not lint or build code samples directly, but the samples repos used throughout our organization do. As a general rule, we prefer all code samples presented in docs to be directly extracted from a CI-enabled code repo using Snipsync to benefit from this. While this may not be practical for every single line of code embedded in docs, it is a best practice.

If you are making changes to code surrounded by Snipsync wrappers, i.e. <!--SNIPSTART someid--> && <!--SNIPEND--> then you will want to make those edits to the actual source code. The location of the source code is written just inside the wrappers.

After you have edited the source code, then you can run yarn snipsync to update that code snippet.

How page routing works

Here is the hierarchy of how the canonical URLs work:

  1. Vercel redirects in vercel.json

    • Old URL → destination URL, before Docusaurus page routing.

  2. Docusaurus route generation

    • routeBasePath: "/" in docusaurus.config.js, so docs live at root, not /docs/*.

  3. Markdown front matter slug field

    • Overrides the generated URL path for that doc page.

  4. File path fallback

    • If no slug exists, URL comes from docs/<path>/<file>.mdx.

  5. Sidebar hierarchy

    • Controls nav placement only; it does not determine the canonical URL.

We do not encourage the use of the slug field in the frontmatter for a page. This field will override the URL and could potentially cause issues with redirects and the sidebar nav. A slug is useful when you want the public URL to be independent of where the file lives in the repo. In most cases, you don't need one.

If you are considering using a custom slug, answer these questions first:

  • Is this page going to be widely linked from blogs, GitHub issues, or other docs?
  • Are you replacing an existing page?
  • Did you already check the redirects in vercel.json?
  • Is it in the page in a folder under the topic that makes the most sense?

Social share images (og:image)

Every doc page automatically gets a social-share preview card generated at build time — the image that shows up when a link to the page is shared in Slack, X, LinkedIn, etc. It's built from the page's title and description. There's nothing to do for a normal page.

The image itself is rendered by a postBuild step (plugins/og-image/), but which image a page points at is decided earlier, during MDX compilation (plugins/og-image/remarkPlugin.js), which writes it into the page's front matter as a real image field — the same field you'd set manually (below). This matters because it's what makes the image survive past the initial page load: Docusaurus renders <head> through react-helmet-async, which re-renders it again on the client the moment a page hydrates. A tag injected after the fact by patching the built HTML would get silently wiped out and replaced with the site-wide default as soon as a real browser (or anything else that executes JavaScript) hydrated the page — only tools that read the raw HTML without running JS (like curl, or most social-share scrapers) would ever see it. Going through real front matter means Docusaurus's own metadata rendering produces the same tag both times, so there's nothing for hydration to revert.

If you want a page to use a different image instead of the generated one, you have two options:

  • Add an image field to the page's front matter, pointing at a static asset (same as the site-wide default in docusaurus.config.js):

    ---
title: My page
image: /img/assets/my-custom-image.png
---

  • For pages that can't use front matter, override it directly with a <Head> component:

    import Head from '@docusaurus/Head';

<Head>
  <meta property="og:image" content="https://docs.temporal.io/img/assets/my-custom-image.png" />
  <meta name="twitter:image" content="https://docs.temporal.io/img/assets/my-custom-image.png" />
</Head>

    The URL must be absolute (https://docs.temporal.io/...), not a relative path.

Either way, the generator leaves the page alone.

This only happens during yarn build (see below) — running yarn start won't show generated or overridden images, since it skips the production build step entirely. The generator itself lives in plugins/og-image/.

Note that yarn build always runs in production mode (NODE_ENV=production), whether that's on your machine, a Vercel preview deployment for a PR, or the real production deploy — so yarn build && yarn serve locally is enough to preview real generated cards on new content before pushing anything; you don't need to wait for an actual deploy.

Local development command reference

The following commands are available to aid in local development:

yarn

This command ensures all the required dependencies are installed.

yarn build

This command triggers a Docusaurus build and results in the browser-consumable JavaScript in the /build directory. Note that the /build directory is ignored by Git.

yarn start

This command spins up a local dev server with hot reload at localhost:3000. It builds from source directly and does not run the production build step, so anything that only happens during yarn build (like generated og:images) won't show up here.

yarn serve

This command serves the contents of the /build directory (the output of yarn build) at localhost:3000, so you can check the actual production output, including generated og:images.

yarn snipsync

This command runs the Snipsync tool per the snipsync.config.yaml file.

--clear

Run yarn snipsync --clear to remove the snippets.