Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (57 loc) · 4.03 KB

CONTRIBUTING.md

File metadata and controls

88 lines (57 loc) · 4.03 KB

Contributing Pulumi Documentation

Pulumi terminology

  • Use pulumi or "the Pulumi CLI" to refer to the CLI.
  • Use pulumi.com to refer to the service.

Documentation structure

  • There is a folder for each heading in the top navigation, such as Install, getting-started, etc.

  • The mapping from documentation page to section and table-of-contents (TOC) is stored largely in each page's front matter, leveraging Hugo Menus. Menus for the CLI commands and API reference are specified in ./config.toml.

Links to other files

We generally use Hugo's relref shortcode when linking to other pages. Examples:

[Install]({{< relref "/docs/get-started/install" >}})
[Outputs]({{< relref "/docs/intro/concepts/programming-model#stack-outputs" >}})

Which, on a page inside the ./content/reference directory, will generate:

<a href="/docs/install/">Install</a>
<a href="/docs/intro/concepts/programming-model/#stack-outputs">Outputs</a>

Hugo tips

  • Redirects. If you rename a file or directory, add a 301 redirect in the front-matter via an alias aliases: [/previous-dir/previousfile.html].

  • Includes.

    • .md files. To share common content across articles, use Hugo Shortcodes. Place a .html file in the [layouts/shortcodes] folder. To include it in a page, use syntax {{< my-shortcode >}}

      For example, our custom cleanup shortcode can be included in .md files, to include common text about cleaning up stack resources:

      {{< cleanup >}}

    • .html layout files. HTML layouts can include other layouts inside the layouts/partials directory, e.g.:

      {{ partial "head.html" . }}

  • Front-matter variables. You can define a front-matter variable in the YAML section at the top of a file. For instance, the you could add the following front matter foo: "bar", and then reference the variable in markdown with the syntax {{< param foo >}}.

    • no_on_this_page Specify this variable to prevent displaying an "On This Page" TOC on the right nav for the page.
    • block_external_search_index Specify this variable to prevent crawlers from indexing the page.
    • exclude_from_pulumi_search_index Specify this variable to prevent the page from appear in internal search results.

Style guide

Language and terminology styles

  • Top level headings use Title Case, where each word starts with a capital letter.
  • All other headings use Sentence case, where only the first word and any proper nouns have a capital letter.
  • Use capitalization only for a proper noun, and use throughout. For example, "stack" should almost always be lowercase in text.

Referring to "things"

  • References to the Pulumi CLI or CLI commands should be enclosed in backticks (e.g., pulumi up).
  • References to UI elements within a webpage should be bold. (e.g., "Go to the Account page in the Pulumi Console and select sync profile with GitHub").
  • Use arrows to indicate a navigation. (e.g., "Go to FooPage > BarItem").

Formatting

  • Use hash marks for headings (#, ##, etc)
  • Use double-asterisks for bold **
  • Use underscore for italic _
  • Use -- for en dashes and --- for em dashes
    • Do not put spaces before or after the dashes
  • Use code fences (triple-backticks) and a language identifier for code formatting and syntax highlighting: 
    ```typescript
const foo = "bar";
```

Sections

If a tutorial has more following tutorials, use a Next steps section at the end. If you're linking to other reference material, use Learn more.

Blog Post Authoring

For instructions on contributing to the Pulumi blog, see BLOGGING.md.