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. You don’t 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.

Types of content

Crossplane documentation has three content sections:

• The Contributing Guide with details on how to contribute to the Crossplane documentation.
• The Knowledge Base is for content related to Crossplane integrations, in-depth articles or how-to guides.
• User documentation are for generic documentation, commonly version-specific.

User documentation vs knowledge base articles

User documentation includes both conceptual and procedural instructions.

Conceptual content describes the background and theory behind the technology. Conceptual documents are helpful to explain the “why” of the technology.

An example of Conceptual content would be describing the role of a Crossplane Provider.

Procedural content is the step-by-step instructions to do something. Procedural content details the “how” of a piece of technology.

An example of a Procedural document would be a step-by-step Crossplane installation guide.

User documentation is more narrowly focused on a single piece or related pieces of technology. For example, installing a Provider and creating a ProviderConfig.

Knowledge base articles are more “free-form” and can describe more than one piece of technology or provide more opinionated examples.

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 graudated the feature.

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

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.