Getting Started

The Crossplane documentation lives in the docs GitHub repository.

Local development

Clone the documentation and use Hugo to build the Crossplane documentation site locally for development and testing.

Clone the docs repository

Clone the Crossplane docs repository with

git clone https://github.com/crossplane/docs.git

Download Hugo

Download Hugo, the static site generator Crossplane docs uses.

Extract and run Hugo with hugo server.

Hugo builds the website and launch a local web server on http://localhost:1313.

Any changes made are instantly reflected on the local web server. No need to restart Hugo.

Contribute to a specific version

Each Crossplane version is a unique folder inside /content.

Make changes to the files in the associated version folder. To make changes across more than one version, change the files in each version folder.

Adding new content

To create new content create a new markdown file in the appropriate location.

To create a new section, create a new directory and an _index.md file in the root.

Front matter

Each page contains metadata called front matter. Each page requires front matter to render.

1---
2title: "A New Page"
3weight: 610
4---

title defines the name of the page. weight determines the ordering of the page in the table of contents. Lower weight pages come before higher weights in the table of contents. The value of weight is otherwise arbitrary.

Alpha and beta features

Note features as alpha or beta in the front matter.

For alpha features set state: alpha and use alphaVersion to provide the version that introduced the feature.

1---
2title: Composition Functions
3state: alpha
4alphaVersion: "1.11"
5---

For beta features set state: beta and use both alhpaVersion and betaVersion to provide the version that introduced and graduated the feature.

1---
2title: Composition Revisions
3state: beta
4alphaVersion: "1.4"
5betaVersion: "1.11"
6---

Descriptions

Hugo uses the description field to populate webpage metadata for search engines.

1---
2title: Compositions
3weight: 30
4aliases: 
5  - composition
6description: "Compositions are a template for creating Crossplane resources"
7---

The description text isn’t displayed anywhere in the docs.

Headings

Use standard markdown for headings (#). The top level heading, a single hash (#) is for the page title. All content headings should be two hashes (##) or more.

Hiding pages

To hide a page from the left-hand navigation use tocHidden: true in the front matter of the page. The docs website skips pages with tocHidden:true when building the menu.

Changing page titles

The version dropdown list that links the same page in different versions together looks for pages with a matching title.

If a page title changes use the front matter value matchTitle: and a value of the old page title.

For example, if an older title was “Original Title” the new page would use:

1title: New Title
2matchTitle: Original Title