22 KiB

Raw Blame History

title	weight
Crossplane Documentation	2000

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.

Local development

Build the Crossplane documentation site locally for development and testing.

Clone the Crossplane repository

Clone the Crossplane repository with

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

Install Make

{{< tab "MacOS" >}} Install make with Homebrew.

brew install make

{{<tab "Linux" >}} Most Linux distributions include make by default. For more information on make for Linux, visit the GNU make website.

{{<tab "Windows" >}} The Crossplane build system doesn't support Windows. {{< /tab >}}

Build the Crossplane documentation

From the crossplane folder run

make docs.run

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

In the crossplane/crossplane 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.

Writing 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.).
Avoid 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.

The Crossplane maintainers recommend the Google developer documentation style guide to help answer questions on proper styling.

Code style guidelines

Use fenced code blocks

Use Markdown fenced code blocks with three backticks (```) for all command examples and outputs.

```
this is a code block
```

Only use a single backtick (`) for commands used in a sentence.

For example, the command kubectl apply is inside a sentence.

Use language hints for proper highlighting

Hugo attempts to determine the language and apply proper styling, but it's not always optimized for readability.

For example, this YAML output isn't automatically detected.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org

All code blocks must include a language definition on the same line as the backticks.

```yaml
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org
```

Find a full list of supported languages in the Chroma documentation.

{{< hint "important" >}} The language definition should optimize for display and not technical correctness. {{< /hint >}}

For example, this uses the shell language hint.

cat test.yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

Using the yaml language hint provides improved readability.

cat test.yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

Code line highlighting

Crossplane docs provide two methods of code highlighting: static and dynamic highlighting.

Static line highlighting

Static highlighting is an "always on" highlight of a line in a code box.

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

Apply a {hl_lines=<line number>} to a code fence.

```yaml {hl_lines=1}
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider
```

To highlight continuous blocks use a range in quotes {hl_lines="1-4"}. For multiple lines, including blocks, create an array of values in square brackets. {hl_lines=[1,2,"4-6"]}.

More information on static highlighting is available in the Hugo syntax highlighting documentation.

Dynamic line highlighting

Dynamic highlighting only highlights a specific line when a read hovers over a specific word outside of the code block. This highlighting style is useful to draw attention to a line of code when explaining a command or argument.

For example hover over the word {{}}kind{{}} to highlight a line in the YAML file.

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

First, apply the {{}}{label=name}{{}} to the code fence.

{{<hint "tip">}} Don't use quotes around the label name. {{< /hint >}}

```yaml {label=example}
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider
```

Next, use the hover shortcode around the word that triggers the highlighting. Provide the matching label name and line number to highlight

{{</* hover label="example" line="2" */>}}commmand{{</* /hover */>}}

{{<hint "note" >}} Hovering triggers a highlight to any code block with the label. Duplicate labels highlight all matching code boxes. {{< /hint >}}

Customize code box copy button

Code boxes automatically have a "copy to clipboard" button that copies the entire contents of the code box.

Customize the lines the button copies with a {copy-lines="<start line>-<end line>"} label on the code block.

For example, to copy lines from 2 to 5 inclusive and not copy the code fence in this example:

```yaml {copy-lines="2-5"}
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider
```

Copying a single line is also supported without using the ending line number. For example to copy only line 3 use {copy-lines="3"}.

{{<hint "important" >}} The line number range must be in quotations. {{< /hint >}}

Combining copying and highlighting in a single comma-seperated annotation.

```yaml {copy-lines="2-5", hl_lines="2-3"}
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider
```

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.

{{<hint "note">}} The img shortcode doesn't support .SVG files. {{< /hint >}}

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:

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

Which generates this responsive image (change your browser size to see it change): {{}}

Links

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

[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,

[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.

{{</* tabs */>}}

{{</* tab "First tab title" */>}}
An example tab. Place anything inside a tab.
{{</* /tab */>}}

{{</* tab "Second tab title" */>}}
A second example tab. 
{{</* /tab */>}}

{{</* /tabs */>}}

This code block renders the following tabs {{< tabs >}}

{{< tab "First tab title" >}} An example tab. Place anything inside a tab. {{< /tab >}}

{{< tab "Second tab title" >}} A second example tab. {{< /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.

{{< hint "note" >}} Notes are useful for calling out optional information. {{< /hint >}}

{{< hint "tip" >}} Use tips to provide context or a best practice. {{< /hint >}}

{{< hint "important" >}} Important hints are for drawing extra attention to something. {{< /hint >}}

{{< hint "warning" >}} Use warning boxes to alert users of things that may cause outages, lose data or are irreversible changes. {{< /hint >}}

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

{{</* hint "note" */>}}
Your box content. This hint box is a note.
{{</* /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.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org
spec:
  group: database.example.org
  names:
    kind: XPostgreSQLInstance
    plural: xpostgresqlinstances
  claimNames:
    kind: PostgreSQLInstance
    plural: postgresqlinstances
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              parameters:
                type: object
                properties:
                  storageGB:
                    type: integer
                required:
                - storageGB
            required:
            - parameters

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

{{</* expand "A large XRD" */>}}
```yaml
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org
```
{{</* /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.

---
title: "A New Page"
weight: 610
---

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/.

{{<hint "important" >}} Don't edit the original Bootstrap stylesheets. It makes the ability to upgrade to future Bootstrap versions difficult or impossible. {{< /hint >}}

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.

{{<hint "note" >}} When creating new styles rely on variables for any color function, even if both themes share the color. {{< /hint >}}

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:

postcss-lightningcss - for building, minimizing and generating a source map.
PurgeCSS - removes unused styles to reduce the CSS file size.
postcss-sort-media-queries- to organize and reduce CSS media queries to remove duplicate and unused CSS.

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 builder

The entire Bootstrap 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 repository.

{{}}

├── content                     # Root for all page content
│   ├── master
│   ├── v1.10
│   ├── v1.8
│   └── v1.9
├── themes                      # Entry point for theme-specific designs
│   └── geekboot
│       ├── assets              # JS and stylesheets
│       │   ├── js              # Bundled and optmized Javascript
│       │   └── scss            # Bootstrap SCSS overrides
│       │       └── bootstrap   # Bootstrap original SCSS files
│       ├── data
│       ├── layouts             # HTML layouts and shortcodes
│       │   ├── _default        # HTML layouts for page types
│       │   │   └── _markup     # Hugo render hooks
│       │   ├── partials        # HTML Template elements
│       │   │   ├── icons
│       │   │   └── utils
│       │   └── shortcodes      # Shortcode features
│       └── static              # Static files across the theme.
│           ├── fonts           # Font files
│           └── img             # Global images
└── utils                       # Files unrelated to Hugo
    └── webpack                 # Files managed or related to webpack
        └── src
            └── js
                └── bootstrap/          # Original Bootstrap JavaScript
                └── colorMode.js        # Color theme switcher
                └── customClipboard.js  # Defines where to put a clipboard icon and what to copy
                └── hoverHighlight.js   # Enables hover to highlight
                └── tabDeepAnchor.js    # Enable anchors inside tabs