Crossplane Documentation

Code of conduct

Crossplane follows the CNCF Code of Conduct.

Taken directly from the code:

As contributors and maintainers in the CNCF community, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in the CNCF community a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

Reporting violations

To report violations contact the Crossplane maintainers at info@crossplane.io or the CNCF at conduct@cncf.io.

Docs source

Crossplane documentation lives in two repositories:

  • Crossplane documentation source is in the Crossplane repository /docs directory.

  • The Crossplane docs website is in the docs repository.

Use crossplane/crossplane for documentation contributions.
Use crossplane/docs for local development or updates involving HTML, CSS or Hugo.

Licensing

The Crossplane documentation is under the Creative Commons Attribution license. CC-BY allows reuse, remixing and republishing of Crossplane documentation with attribution to the Crossplane organization.

Issues and feature requests

Open an issue to report a problem or request documentation content.

Contributing

Documentation content contributions are always welcome.

The Crossplane documentation source is in the Crossplane repository /docs directory.

Crossplane recommends using the website repository for local development. When a contribution is ready, submit a pull request to the Crossplane repository.

Local development

Build the Crossplane documentation site locally for development and testing.

Clone the documentation site

Clone the documentation repository with

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

Download the Hugo static site generator

Crossplane uses Hugo, a static site generator.

Download a Hugo v0.101.0 or later from the Hugo releases.

Build the Crossplane documentation

From the crossplane.github.io folder run

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

The documentation location for the various Crossplane versions are different for the Crossplane source and docs website.

Crossplane repository

In the crossplane/crossplane repository documentation is in the /docs directory.

Each active release has a /docs folder in a branch called release-<version>. For example, v1.10 docs are in the branch release-1.10.

To contribute to a specific release submit a pull-request to the release-<version> or master branch.

The next Crossplane release uses master as the starting documentation.

Website repository

The docs website repository combines all active versions in the /content directory.

Style guidelines

The official Crossplane documentation style guide is still under construction. Guiding principals for the documentation include:

  • Avoid passive voice.
  • Use sentence-case headings.
  • Wrap lines at 80 characters.
  • Use present tense.
  • Spell out numbers less than 10, except for percentages, time and versions.
  • Capitalize “Crossplane” and “Kubernetes.”
  • Spell out the first use of an acronym unless it’s common to new Crossplane users. When in doubt, spell it out first.
  • Don’t use cliches.
  • Use contractions for phrases like “do not”, “cannot”, “is not” and related terms.
  • Don’t use Latin terms (i.e., e.g., etc.).
  • Don’t use gerund headings (-ing words).
  • Try and limit sentences to 25 words or fewer.
  • Be descriptive in link text. Don’t use “click here” or “read more”.

Crossplane documentation is adopting Vale and relies on the Upbound Vale definitions for style guidelines.

Beyond Vale, Crossplane recommends Grammarly and Hemingway Editor to improve writing quality.

Docs site styling features

The Crossplane documentation supports multiple styling features to improve readability.

Images

Crossplane supports standard Markdown image syntax but using the img shortcode is strongly recommended.

Images using the shortcode are automatically converted to webp image format, compressed and use responsive image sizing.

Note
The img shortcode doesn’t support .SVG files.

The shortcode requires a src (relative to the file using the shortcode), an alt text and an optional size.

The size can be one of:

  • xtiny - Resizes the image to 150px.
  • tiny - Resizes the image to 320px.
  • small - Resizes the image to 600px.
  • medium - Resizes the image to 1200px.
  • large - Resizes the image to 1800px.

By default the image isn’t resized.

An example of using the img shortcode:

1{{< img src="/media/banner.png" alt="Crossplane Popsicle Truck" size="small" >}}

Which generates this responsive image (change your browser size to see it change): Crossplane Popsicle Truck

Crossplane docs support standard Markdown links but Crossplane prefers link shortcodes for links between docs pages. Using shortcodes prevents incorrect link creation and notifies which links to change after moving a page.

Between docs pages

For links between pages use a standard Markdown link in the form:

[Link text](link)

Crossplane recommends using the Hugo ref shortcode with the path of the file relative to /content for the link location.

For example, to link to the master release index page use

1[master branch documentation]({{< ref "master/_index.md" >}})

The ref value is of the markdown file, including .md extension.

If the ref value points to a page that doesn’t exist, Hugo fails to start.

Linking to external sites

Minimize linking to external sites. When linking to any page outside of crossplane.io use standard markdown link syntax without using the ref shortcode.

For example,

1[Go to Upbound](http://upbound.io)

Tabs

Use tabs to present information about a single topic with multiple exclusive options. For example, creating a resource via command-line or GUI.

To create a tab set, first create a tabs shortcode and use multiple tab shortcodes inside for each tab.

 1{{< tabs >}}
 2
 3{{< tab "First tab title" >}}
 4An example tab. Place anything inside a tab.
 5{{< /tab >}}
 6
 7{{< tab "Second tab title" >}}
 8A second example tab. 
 9{{< /tab >}}
10
11{{< /tabs >}}

This code block renders the following tabs

An example tab. Place anything inside a tab.
A second example tab.

Both tab and tabs require opening and closing tags. Unclosed tags causes Hugo to fail.

Hints and alert boxes

Hint and alert boxes provide call-outs to important information to the reader. Crossplane docs support four different hint box styles.

Note
Notes are useful for calling out optional information.
Tip
Use tips to provide context or a best practice.
Important
Important hints are for drawing extra attention to something.
Warning
Use warning boxes to alert users of things that may cause outages, lose data or are irreversible changes.

Create a hint by using a shortcode in your markdown file:

1{{< hint "note" >}}
2Your box content. This hint box is a note.
3{{< /hint >}}

Use note, tip, important, or warning as the hint value.

The hint shortcode requires opening and closing tags. Unclosed tags causes Hugo to fail.

Hide long outputs

Some outputs may be verbose or only relevant for a small audience. Use the expand shortcode to hide blocks of text by default.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xpostgresqlinstances.database.example.org
 5spec:
 6  group: database.example.org
 7  names:
 8    kind: XPostgreSQLInstance
 9    plural: xpostgresqlinstances
10  claimNames:
11    kind: PostgreSQLInstance
12    plural: postgresqlinstances
13  versions:
14  - name: v1alpha1
15    served: true
16    referenceable: true
17    schema:
18      openAPIV3Schema:
19        type: object
20        properties:
21          spec:
22            type: object
23            properties:
24              parameters:
25                type: object
26                properties:
27                  storageGB:
28                    type: integer
29                required:
30                - storageGB
31            required:
32            - parameters

The expand shortcode can have a title, the default is “Expand.”

1{{< expand "A large XRD" >}}
2```yaml
3apiVersion: apiextensions.crossplane.io/v1
4kind: CompositeResourceDefinition
5metadata:
6  name: xpostgresqlinstances.database.example.org
7```
8{{< /expand >}}

The expand shortcode requires opening and closing tags. Unclosed tags causes Hugo to fail.

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.

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.

Docs website

The Crossplane document website is in a unique website GitHub repository.

Crossplane uses Hugo, a static site generator. Hugo influences the directory structure of the website repository.

The /content directory is the root directory for all documentation content.

The /themes/geekboot directory is the root directory for all website related files, like HTML templates, shortcodes and global media files.

The /utils/ directory is for JavaScript source code used in the website.

The /themes/geekboot/assets folder contains all (S)CSS and compiled JavaScript for the website.

CSS

Crossplane documentation uses Bootstrap 5.2. Unmodified Bootstrap SCSS files are in /themes/geekboot/assets/scss/bootstrap/. Any docs-specific overrides are in per-element SCSS files located one directory higher in /themes/geekboot/assets/scss/.

Important
Don’t edit the original Bootstrap stylesheets. It makes the ability to upgrade to future Bootstrap versions difficult or impossible.

Color themes

Crossplane docs support a light and dark color theme that’s applied via CSS variables.

Universal and default variables are defined in /themes/geekboot/assets/scss/_variables.scss.

Provide theme specific color overrides in /themes/geekboot/assets/scss/light-mode.scss or /themes/geekboot/assets/scss/light-mode.scss.

Note
When creating new styles rely on variables for any color function, even if both themes share the color.

SCSS compilation

Hugo compiles the SCSS to CSS. Local development doesn’t require SCSS installed.

For local development (when using hugo server) Hugo compiles SCSS without any optimizations.

For production (publishing on Netlify or using hugo server --environment production) Hugo compiles SCSS and optimizes the CSS with PostCSS. The PostCSS configuration is in /postcss.config.js. The optimizations includes:

Optimizing CSS locally with PostCSS requires installing extra packages.

  • Sass
  • NPM
  • NPM packages defined in /package.json with npm install.

JavaScript

A goal of the documentation website is to use as little JavaScript as possible. Unless the script provides a significant improvement in performance, capability or user experience.

To make local development there are no run-time dependencies for JavaScript.

Runtime JavaScript is in /themes/geekboot/assets/js/. Webpack has bundled, minified and compressed the JavaScript.

The source JavaScript is in /utils/webpack/src/js and requires Webpack to bundle and optimize the code.

  • colorMode.js provides the ability to change the light/dark mode color theme.
  • tabDeepAnchor.js rewrites anchor links inside tabs to open a tab and present the anchor.
  • globalScripts.js is the point of entry for Webpack to determine all dependencies. This bundles instant.page and Bootstrap’s JavaScript.

Bootstrap JavaScript

The entire Bootstap JavaScript source is in /utils/webpack/src/js/bootstrap.

Adding a new Bootstrap feature requires importing it in globalScripts.js.

By importing only the necessary Bootstrap JavaScript features, reduces the bundle size.

Annotated website tree

Expand the tab below to see an annotated tree output of the website repo.

 1├── content                     # Root for all page content
 2│   ├── master
 3│   ├── v1.10
 4│   ├── v1.8
 5│   └── v1.9
 6├── themes                      # Entry point for theme-specific designs
 7│   └── geekboot
 8│       ├── assets              # JS and stylesheets
 9│       │   ├── js              # Bundled and optmized Javascript
10│       │   └── scss            # Bootstrap SCSS overrides
11│       │       └── bootstrap   # Bootstrap original SCSS files
12│       ├── data
13│       ├── layouts             # HTML layouts and shortcodes
14│       │   ├── _default        # HTML layouts for page types
15│       │   │   └── _markup     # Hugo render hooks
16│       │   ├── partials        # HTML Template elements
17│       │   │   ├── icons
18│       │   │   └── utils
19│       │   └── shortcodes      # Shortcode features
20│       └── static              # Static files across the theme.
21│           ├── fonts           # Font files
22│           └── img             # Global images
23└── utils                       # Files unrelated to Hugo
24    └── webpack                 # Files managed or related to webpack
25        └── src
26            └── js
27                └── bootstrap/  # Original Bootstrap JavaScript
28                └── colorMode.js  # Color theme switcher
29                └── tabDeepAnchor.js # Enable anchors inside tabs