Contributors guide

In this guide, you’ll learn how to contribute to the Dapr docs repository. Since Dapr docs are published to docs.dapr.io, you must make sure your contributions compile and publish correctly.

Prerequisites

Before contributing to the Dapr docs:

• Review the guidance around general Dapr project contributions.
• Install and set up your local environment with Hugo with the Docsy theme. Follow the instructions in the repository README.md.
• Fork and clone the docs repository.

Branch guidance

The Dapr docs handles branching differently than most code repositories. Instead of a main branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the Docs repo

Generally, all of your docs updates should point to docs branch for the latest release of Dapr. The latest release is the default branch [https://github.com/dapr/docs]. For example, if you are fixing a typo, adding notes, or clarifying a point, make your changes into the default Dapr branch.

For any docs changes applicable to a release candidate or a pre-release version of the docs, point your changes into that particular branch. For example, if you are documenting an upcoming change to a component or the runtime, make your changes to the pre-release branch.

Style and tone

Style and tone conventions should be followed throughout all Dapr documentation for consistency across all docs:

Diagrams and images

Diagrams and images are invaluable visual aids for documentation pages. Use the diagram style and icons in the Dapr Diagrams template deck.

Some diagrams are generated from code instead of drawn in the deck. If you are adding or changing one of those, see Generated diagrams below.

The process for creating diagrams for your documentation:

1. Download the Dapr Diagrams template deck to use the icons and colors.
2. Add a new slide and create your diagram.
3. Screen capture the diagram as high-res PNG file and save in the images folder.
4. Name your PNG files using the convention of a concept or building block so that they are grouped.

• For example: service-invocation-overview.png.
• For more information on calling out images using shortcode, see the Images guidance section below.

1. Add the diagram to the appropriate section in your documentation using the HTML <image> tag.
2. In your PR, comment the diagram slide (not the screen capture) so it can be reviewed and added to the diagram deck by maintainers.

Generated diagrams

Some diagrams in these docs are not images at all. They are generated SVG scenes: a small JavaScript file describes the drawing, a build step renders it, and the page inlines the result. A generated diagram paints in the site’s own theme tokens, so it follows the light and dark toggle; its text is real text, so it can be selected, searched and read aloud by a screen reader; and a change to it is reviewed as a diff rather than as a replacement screenshot.

Follow the diagram skill at skills/vector-2d-diagrams/SKILL.md whenever you add or change one. It is the design system for these drawings: the canvas, colour and line rules, the shape vocabulary, where labels and arrows go, how brand marks are sourced and licensed, the accessibility rules, the workflow to follow, and a list of the traps already hit. Read it yourself, or point your coding agent at it. Diagrams drawn to it look like one another, which is the whole point of having it.

The workflow, in short:

1. Write the scene in diagrams/scenes/<name>.mjs and register it in diagrams/scenes/index.mjs.

2. Run npm run export:diagrams. It writes the inlined drawing to daprdocs/assets/diagrams/<name>.svg and a standalone copy to daprdocs/static/diagrams/<name>.svg. Then run npm run export:pngs, which renders the standalone copy to daprdocs/static/diagrams/<name>.png, the file behind the page’s “Download PNG” button. Commit all three. The two steps are not alike: the SVG export is plain Node, but the PNG step drives a browser, so it needs Chromium installed (npx playwright install chromium). It only re-renders the scenes that changed, so an unchanged diagram’s PNG does not churn in git. --force re-renders everything.

3. Place it on the page with the diagram shortcode:

   {{< diagram service-invocation >}}
   

   A drawing that reads better below the full column width takes an optional width, a whole percentage from 10 to 100. Hugo does not allow positional and named parameters in the same call, so a call that passes width names the scene as well:

   {{< diagram name="api-scoping" width="70" >}}
   

   A missing or misspelled scene name fails the build instead of rendering nothing.

4. Add the scene to SCENE_ROWS in tests/diagrams.spec.js with every label it must draw. That spec fails on a scene or a call site that has no row, so no diagram ships untested.

5. Render it and look at it in both themes before opening your PR. The numeric tests pass on a mark that is invisible and on a label drawn twice in the same place.

6. Run the four checks CI runs, in this order:

   npm run export:diagrams -- --check
   npm run check:pngs
   npm run test:diagrams
   npm run test:layout
   

   The first three are plain Node and finish in seconds; CI runs them before it installs a browser. test:layout needs Chromium and runs the full Playwright suite, which takes several minutes. A committed SVG that no longer matches a fresh render fails the first, and a committed PNG that no longer matches its scene fails the second, so a scene edited without re-running npm run export:diagrams and npm run export:pngs does not get through. npm run check:pngs only compares hashes, so it needs no browser even though regenerating the PNGs does.

Pages that have not been converted still use the template deck process above. The two sit side by side; there is no need to convert a diagram just because you are editing the page it sits on.

Contributing a new docs page

If you’re creating a new article, make sure you:

• Place the new document in the correct place in the hierarchy.
• Avoid creating new sections. Most likely, the proper place is already in the docs hierarchy.
• Include complete Hugo front-matter.

Select the topic type below to view a suggested template to help you get started.

Requirements for docs.dapr.io

Make sure your contribution doesn’t break the website build. The way Hugo builds the website requires following the guidance below:

Files and folder names

File and folder names should be globally unique. - \service-invocation - service-invocation-overview.md

Front-matter

Front-matter is what takes regular markdown files and upgrades them into Hugo compatible docs for rendering into the nav bars and ToCs.

Every page needs a section at the top of the document like this:

---
type: docs
title: "TITLE FOR THE PAGE"
linkTitle: "SHORT TITLE FOR THE NAV BAR"
weight: (number)
description: "1+ SENTENCES DESCRIBING THE ARTICLE"
---

Example

---
type: docs
title: "Service invocation overview"
linkTitle: "Overview"
weight: 10
description: "A quick overview of Dapr service invocation and how to use it to invoke services within your application"
---

Weight determines the order of the pages in the left sidebar, with 0 being the top-most.

Front-matter should be completed with all fields including type, title, linkTitle, weight, and description.

• title should be 1 sentence, no period at the end
• linkTitle should be 1-3 words, with the exception of How-to at the front.
• description should be 1-2 sentences on what the reader will learn, accomplish, or do in this doc.

As per the styling conventions, titles should only capitalize the first word and proper nouns, with the exception of “How-To:”

• “Getting started with Dapr service invocation”
• “How-To: Setup a local Redis instance”

Referencing other pages

Hugo ref and relref shortcodes are used to reference other pages and sections. These shortcodes also allow the build to break if a page is incorrectly renamed or removed.

For example, this shortcode, written inline with the rest of the markdown page, will link to the _index.md of the section/folder name:

{{% ref "folder" %}}

While this shortcode will link to a specific page:

{{% ref "page" %}}

All pages and folders need to have globally unique names in order for the ref shortcode to work properly. If there are duplicate names, the build will break and an error will be thrown.

Referencing sections in other pages

To reference a specific section in another page, add #section-short-name to the end of your reference.

As a general rule, the section short name is the text of the section title, all lowercase, with spaces changed to “-”. You can check the section short name by:

1. Visiting the website page.
2. Clicking the link icon (🔗) next to the section.
3. Seeing how the URL renders in the nav bar.
4. Copying the content after the “#” for your section shortname.

As an example, for this specific section, the complete reference to the page and section would be:

{{% ref "contributing-docs#referencing-sections-in-other-pages" %}}

Shortcodes

The following are useful shortcodes for writing Dapr documentation

Images

The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HTML is used.

Begin by placing images under /daprdocs/static/images with the naming convention of [page-name]-[image-name].[png|jpg|svg].

Then link to the image using:

<img src="/images/[image-filename]" width=1000 alt="Description of image">

Don’t forget to set the alt attribute to keep the docs readable and accessible.

Example

This HTML will display the dapr-overview.png image on the overview.md page:

<img src="/images/overview-dapr-overview.png" width=1000 alt="Overview diagram of Dapr and its building blocks">

Tabbed content

Tabs are made possible through Hugo shortcodes.

The overall format is:

  

      
        Tab1
      
    

      
        Tab2
      
    



    

        
[Content for Tab1]

    
    

        
[Content for Tab2]

    

All content you author will be rendered to markdown, so you can include images, code blocks, YouTube videos, and more.

Example

  

      
        Windows
      
    

      
        Linux
      
    

      
        MacOS
      
    



    

        
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
brew install dapr/tap/dapr-cli

This example will render to this:

• Windows
• Linux
• MacOS

powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash

brew install dapr/tap/dapr-cli

YouTube videos

Hugo can automatically embed YouTube videos using a shortcode:

{{% youtube [VIDEO ID] %}}

Example

Given the video https://youtu.be/dQw4w9WgXcQ

The shortcode would be:

{{% youtube dQw4w9WgXcQ %}}

Buttons

To create a button in a webpage, use the button shortcode.

An optional “newtab” parameter will indicate if the page should open in a new tab. Options are “true” or “false”. Default is “false”, where the page will open in the same tab.

Link to an external page

{{% button text="My Button" link="https://example.com" %}}

Link to another docs page

You can also reference pages in your button as well:

{{% button text="My Button" page="contributing" newtab="true" %}}

Button colors

You can customize the colors using the Bootstrap colors:

{{% button text="My Button" link="https://example.com" color="primary" %}}
{{% button text="My Button" link="https://example.com" color="secondary" %}}
{{% button text="My Button" link="https://example.com" color="success" %}}
{{% button text="My Button" link="https://example.com" color="danger" %}}
{{% button text="My Button" link="https://example.com" color="warning" %}}
{{% button text="My Button" link="https://example.com" color="info" %}}

My Button

My Button

My Button

My Button

My Button

My Button

References

Docsy authoring guide

Translations

The Dapr Docs supports adding language translations into the docs using git submodules and Hugo’s built in language support.

You can find an example PR of adding Chinese language support in PR 1286.

Steps to add a language:

• Open an issue in the Docs repo requesting to create a new language-specific docs repo

• Once created, create a git submodule within the docs repo:

  git submodule add <remote_url> translations/<language_code>
  

• Add a language entry within daprdocs/config.toml:

   [languages.<language_code>]
     title = "Dapr Docs"
     weight = 3
     contentDir = "content/<language_code>"
     languageName = "<language_name>"
  

• Create a mount within daprdocs/config.toml:

  [[module.mounts]]
    source = "../translations/docs-<language_code>/content/<language_code>"
    target = "content"
    lang = "<language_code>"
  

• Repeat above step as necessary for all other translation directories.

Next steps

Get started by copying and working from one of the Dapr doc templates.