--- title: "Crossplane Documentation" weight: 2000 --- ## Code of conduct Crossplane follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). 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](https://github.com/crossplane/crossplane) `/docs` directory. * The Crossplane docs website is in the [docs](https://github.com/crossplane/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](https://creativecommons.org/licenses/by/4.0/) license. CC-BY allows reuse, remixing and republishing of Crossplane documentation with attribution to the Crossplane organization. ### Issues and feature requests Open an [issue](https://github.com/crossplane/crossplane/issues) to report a problem or request documentation content. ## Contributing Documentation content contributions are always welcome. The Crossplane documentation source is in the [Crossplane repository](https://github.com/crossplane/crossplane) `/docs` directory. Crossplane recommends using the [website repository](https://github.com/crossplane/crossplane.github.io) for local development. When a contribution is ready, submit a pull request to the [Crossplane repository](https://github.com/crossplane/crossplane). ### Local development Build the Crossplane documentation site locally for development and testing. #### Clone the documentation site Clone the [documentation repository](https://github.com/crossplane/crossplane.github.io) with ```command git clone https://github.com/crossplane/crossplane.github.io.git ``` #### Download the Hugo static site generator Crossplane uses [Hugo](https://github.com/gohugoio/hugo), a static site generator. Download a Hugo v0.101.0 or later from the [Hugo releases](https://github.com/gohugoio/hugo/releases/tag/v0.106.0). #### Build the Crossplane documentation From the `crossplane.github.io` folder run ```command hugo server ``` Hugo builds the website and launch a local web server on [http://localhost:1313](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](https://github.com/crossplane/crossplane) repository documentation is in the `/docs` directory. Each active release has a `/docs` folder in a branch called `release-`. For example, v1.10 docs are in the branch [release-1.10](https://github.com/crossplane/crossplane/tree/release-1.10). To contribute to a specific release submit a pull-request to the `release-` or `master` branch. The next Crossplane release uses `master` as the starting documentation. #### Website repository The [docs website repository](https://github.com/crossplane/crossplane.github.io) 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](https://www.grammarly.com/blog/passive-voice/). * Use [sentence-case headings](https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case). * Wrap lines at 80 characters. * Use [present tense](https://www.grammarly.com/blog/simple-present/). * 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](https://www.topcreativewritingcourses.com/blog/common-cliches-in-writing-and-how-to-avoid-them). * 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](https://owl.purdue.edu/owl/general_writing/mechanics/gerunds_participles_and_infinitives/index.html) headings (-ing words). * Try and limit sentences to 25 words or fewer. * [Be descriptive in link text](https://usability.yale.edu/web-accessibility/articles/links#link-text). Don't use "click here" or "read more". Crossplane documentation is adopting [Vale](https://github.com/errata-ai/vale) and relies on the [Upbound Vale definitions](https://github.com/upbound/vale) for style guidelines. Beyond Vale, Crossplane recommends [Grammarly](https://www.grammarly.com/) and [Hemingway Editor](https://hemingwayapp.com/) 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](https://www.markdownguide.org/basic-syntax/#images-1) 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. {{}} 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: ```html {{}} ``` Which generates this responsive image (change your browser size to see it change): {{Crossplane Popsicle Truck}} ### Links Crossplane docs support standard [Markdown links](https://www.markdownguide.org/basic-syntax/#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](https://gohugo.io/content-management/shortcodes/#ref-and-relref) with the path of the file relative to `/content` for the link location. For example, to link to the `master` release index page use ```markdown [master branch documentation]({{}}) ``` 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](https://www.markdownguide.org/basic-syntax/#links) without using the `ref` shortcode. For example, ```markdown [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. ```html {{}} {{}} An example tab. Place anything inside a tab. {{}} {{}} A second example tab. {{}} {{}} ``` 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 >}} {{< /tabs >}} 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: ```html {{}} Your box content. This hint box is a note. {{}} ``` 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. {{}} ```yaml 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 ``` {{< /expand >}} The `expand` shortcode can have a title, the default is "Expand." ````yaml {{}} ```yaml apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: name: xpostgresqlinstances.database.example.org ``` {{}} ```` 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](https://gohugo.io/content-management/front-matter/). Each page requires front matter to render. ```yaml --- 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](https://github.com/crossplane/docs). Crossplane uses [Hugo](https://gohugo.io/), 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](https://getbootstrap.com/docs/5.2/getting-started/introduction/). 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/`. {{}} 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`. {{}} 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](https://postcss.org/). The PostCSS configuration is in `/postcss.config.js`. The optimizations includes: * [postcss-lightningcss](https://github.com/onigoetz/postcss-lightningcss) - for building, minimizing and generating a source map. * [PurgeCSS](https://purgecss.com/plugins/postcss.html) - removes unused styles to reduce the CSS file size. * [postcss-sort-media-queries](https://github.com/yunusga/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](https://sass-lang.com/install) * [NPM](https://www.npmjs.com/) * 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](https://webpack.js.org/) has bundled, minified and compressed the JavaScript. The source JavaScript is in `/utils/webpack/src/js` and requires [Webpack](https://webpack.js.org/) 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](https://instant.page/) and [Bootstrap's JavaScript](https://getbootstrap.com/docs/5.2/getting-started/javascript/). #### Bootstrap JavaScript The entire [Bootstap JavaScript source](https://github.com/twbs/bootstrap/tree/main/js/src) 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. {{}} ```shell ├── 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 └── tabDeepAnchor.js # Enable anchors inside tabs ``` {{}}