mirror of https://github.com/crossplane/docs.git
Add a bunch more contrib info (#758)
* more contrib info Signed-off-by: Pete Lumbis <pete@upbound.io> * expand build and netlify things Signed-off-by: Pete Lumbis <pete@upbound.io> * Add lots of comments Signed-off-by: Pete Lumbis <pete@upbound.io> * add comments Signed-off-by: Pete Lumbis <pete@upbound.io> * +Algolia, DocSearch, NodeJS Signed-off-by: Pete Lumbis <pete@upbound.io> --------- Signed-off-by: Pete Lumbis <pete@upbound.io>
This commit is contained in:
Pete Lumbis
GitHub
parent
3e9e10671c
commit
bd0f99a77f
47
config.yaml
47
config.yaml
|
|
@ -2,13 +2,20 @@ baseURL: "/"
|
|||
enableRobotsTXT: True
|
||||
languageCode: "en-us"
|
||||
title: "Crossplane"
|
||||
|
||||
# directory name in /themes
|
||||
theme: "geekboot"
|
||||
|
||||
# enable Lastmod parameter for each page. Placed in an HTML meta tag.
|
||||
enableGitInfo: true
|
||||
uglyurls: false
|
||||
|
||||
# Crossplane docs don't use the Hugo taxonomy or term page kinds.
|
||||
# Disabling provides a small build speedup
|
||||
disableKinds:
|
||||
- taxonomy
|
||||
- term
|
||||
|
||||
# Enable RSS feeds for sections
|
||||
outputs:
|
||||
home:
|
||||
- html
|
||||
|
|
@ -18,28 +25,43 @@ outputs:
|
|||
taxonomy:
|
||||
term:
|
||||
|
||||
|
||||
# Don't publish the README.md file in the /public folder
|
||||
ignoreFiles:
|
||||
- README.md
|
||||
|
||||
# build.writeStats is used to optimize CSS.
|
||||
# the netlify_build.sh script uncomments this.
|
||||
# The default comment means users don't need Hugo extended for authoring.
|
||||
build:
|
||||
# writeStats: true
|
||||
|
||||
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
# Allow mixing markdown and HTML. Required for Vale and some in-line
|
||||
# styling.
|
||||
# Okay to run `unsafe: true` since we review .md file inputs
|
||||
# More info: https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
|
||||
unsafe: true
|
||||
tableOfContents:
|
||||
# Which heading levels to include in the right-side table of contents
|
||||
startLevel: 1
|
||||
endLevel: 9
|
||||
highlight:
|
||||
# Enable syntax styling for code fence (```) blocks
|
||||
codeFences: true
|
||||
# Use classes instead of inline HTML styles for syntax decoration
|
||||
noClasses: false
|
||||
# Include line numbers to the left of a code fence box
|
||||
linenos: true
|
||||
# Make the line numbers anchor links
|
||||
anchorLineNos: true
|
||||
# Don't put the line numbers in tables and only use SPAN elements. For CSS styling.
|
||||
lineNumbersInTable: false
|
||||
|
||||
module:
|
||||
# Mounts give Hugo access to images and YAML for compile-time processing.
|
||||
mounts:
|
||||
- source: content
|
||||
target: content
|
||||
|
|
@ -57,30 +79,21 @@ module:
|
|||
includeFiles:
|
||||
- "**/api/**.yaml"
|
||||
|
||||
# Give Hugo access to environmental variables matching a given regex.
|
||||
# These give Hugo access to Netlify data to generate proper URLs
|
||||
security:
|
||||
funcs:
|
||||
getenv:
|
||||
- ^CONTEXT
|
||||
- ^REVIEW_ID
|
||||
|
||||
# Global parameters accessible by any Page
|
||||
params:
|
||||
# The current "latest" version. Used in the version dropdown
|
||||
latest: "1.15"
|
||||
upboundLink: "https://www.upbound.io/"
|
||||
slackLink: "https://slack.crossplane.io/"
|
||||
githubLink: "https://github.com/crossplane/crossplane"
|
||||
twitterLink: "https://twitter.com/crossplane_io"
|
||||
forumLink: "https://groups.google.com/forum/#!forum/crossplane-dev"
|
||||
youtubeLink: "https://www.youtube.com/channel/UC19FgzMBMqBro361HbE46Fw"
|
||||
podcastLink: "https://www.youtube.com/playlist?list=PL510POnNVaaYFuK-B_SIUrpIonCtLVOzT"
|
||||
blogLink: "https://blog.crossplane.io/"
|
||||
communityMeetingLink: "https://github.com/crossplane/crossplane/#get-involved"
|
||||
cncfLink: "https://www.cncf.io/"
|
||||
prodFormLink: "https://docs.google.com/forms/d/e/1FAIpQLSev-5clADSdkwi_wiFqBCAECeIoAQDE91chBbeWbvyTjRCeYg/viewform"
|
||||
infoMailToLink: "mailto:info@crossplane.io"
|
||||
upboundGithubLink: "https://github.com/upbound"
|
||||
docs: true
|
||||
repoLink: "https://github.com/crossplane/crossplane"
|
||||
anchors:
|
||||
# Generate heading anchors for any heading between min and max
|
||||
min: 2
|
||||
max: 5
|
||||
# description for search engines.
|
||||
description: "Crossplane lets you build a control plane with Kubernetes-style declarative and API-driven configuration and management for anything."
|
||||
|
|
|
|||
|
|
@ -9,9 +9,9 @@ for source code used in documentation.
|
|||
|
||||
|
||||
## Use fenced code blocks
|
||||
Use Markdown [fenced code
|
||||
blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) with
|
||||
three backticks (` ``` `) for
|
||||
Use Markdown
|
||||
[fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)
|
||||
with three backticks (` ``` `) for
|
||||
all command examples and outputs.
|
||||
|
||||
````markdown
|
||||
|
|
@ -24,6 +24,10 @@ Only use a single backtick (`` ` ``) for commands used in a sentence.
|
|||
|
||||
For example, the command `kubectl apply` is inside a sentence.
|
||||
|
||||
{{< hint "warning" >}}
|
||||
Vale doesn't validate terms inside single backtick or fenced code blocks.
|
||||
{{< /hint >}}
|
||||
|
||||
## Use language hints for proper highlighting
|
||||
Hugo attempts to determine the language and apply proper styling, but it's
|
||||
not always optimized for readability.
|
||||
|
|
|
|||
|
|
@ -134,6 +134,23 @@ betaVersion: "1.11"
|
|||
---
|
||||
```
|
||||
|
||||
#### Descriptions
|
||||
|
||||
Hugo uses the `description` field to populate webpage metadata for search
|
||||
engines.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Compositions
|
||||
weight: 30
|
||||
aliases:
|
||||
- composition
|
||||
description: "Compositions are a template for creating Crossplane resources"
|
||||
---
|
||||
```
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -4,11 +4,82 @@ weight: 600
|
|||
description: "Learn how the docs and our tools are built"
|
||||
---
|
||||
|
||||
The Crossplane document website is in a unique [website GitHub
|
||||
repository](https://github.com/crossplane/docs).
|
||||
The Crossplane document website is in a standalone
|
||||
[GitHub repository](https://github.com/crossplane/docs) separate from Crossplane
|
||||
core.
|
||||
|
||||
Crossplane uses [Hugo](https://gohugo.io/), a static site generator. Hugo
|
||||
influences the directory structure of the website repository.
|
||||
The Crossplane docs tools consist of:
|
||||
* [Netlify](https://netlify.com/) - web hosting and DNS provided by the CNCF.
|
||||
* [Hugo](https://gohugo.io/) - to compile markdown to static HTML.
|
||||
* [Bootstrap](https://getbootstrap.com/docs/5.2/) - for pre-built CSS options.
|
||||
* [PostCSS](https://postcss.org/) - for CSS optimization.
|
||||
* [Webpack](https://webpack.js.org/) - for Javascript optimization.
|
||||
|
||||
|
||||
## Netlify
|
||||
|
||||
Builds for production deploys and PR previews are automatically done by Netlify.
|
||||
|
||||
{{< hint "note" >}}
|
||||
The CNCF controls Netlify access.
|
||||
{{< /hint >}}
|
||||
|
||||
Settings for Netlify are inside
|
||||
[`netlify.toml`](https://github.com/crossplane/docs/blob/master/netlify.toml).
|
||||
|
||||
Settings inside the `netlify.toml` file override any settings in the Netlify web
|
||||
interface.
|
||||
|
||||
The
|
||||
[`build`](https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/netlify.toml#L1)
|
||||
directive defines what Netlify does to build the site.
|
||||
|
||||
The
|
||||
[`HUGO_VERSION`](https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/netlify.toml#L7)
|
||||
settings defines which version of Hugo Netlify uses.
|
||||
|
||||
The
|
||||
[`redirects`](https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/netlify.toml#L9)
|
||||
are server side HTTP redirects for moved pages.
|
||||
|
||||
The [Netlify documentation](https://docs.netlify.com/configure-builds/file-based-configuration/)
|
||||
has more information about configuring `netlify.toml`.
|
||||
|
||||
Netlify automatically detects the
|
||||
[`package.json`](https://github.com/crossplane/docs/blob/master/package.json)
|
||||
file and loads the listed NodeJS dependencies.
|
||||
|
||||
<!-- vale off -->
|
||||
### netlify_build.sh
|
||||
<!-- vale on -->
|
||||
|
||||
During a build Netlify runs the Bash script
|
||||
[`netlify_build.sh`](https://github.com/crossplane/docs/blob/master/netlify_build.sh).
|
||||
|
||||
The script creates a new docs section called `latest` and copies the defined
|
||||
`LATEST_VER` to `/latest`.
|
||||
|
||||
Next the script enables `writeStats` in the Hugo configuration file.
|
||||
|
||||
Then, using the Netlify `$CONTEXT`
|
||||
[environmental variable](https://docs.netlify.com/configure-builds/environment-variables/#build-metadata)
|
||||
Hugo runs, defining the [`BaseURL`](https://gohugo.io/methods/site/baseurl/) to
|
||||
use for generating internal links.
|
||||
|
||||
## Hugo
|
||||
Crossplane uses [Hugo](https://gohugo.io/), a static site generator.
|
||||
|
||||
Hugo combines HTML templates, markdown content and generates static HTML
|
||||
content.
|
||||
|
||||
{{<hint "note" >}}
|
||||
The Hugo web server is only used for local development. Crossplane documentation
|
||||
uses Netlify for hosting.
|
||||
|
||||
Hugo only acts as an HTML compiler.
|
||||
{{< /hint >}}
|
||||
|
||||
Hugo influences the directory structure of the repository.
|
||||
|
||||
The `/content` directory is the root directory for all documentation content.
|
||||
|
||||
|
|
@ -17,23 +88,33 @@ files, like HTML templates, shortcodes and global media files.
|
|||
|
||||
The `/utils/` directory is for JavaScript source code and files unrelated to
|
||||
Hugo used in the website.
|
||||
<!-- vale Crossplane.Spelling = NO -->
|
||||
The `/themes/geekboot/assets` folder contains all (S)CSS and compiled JavaScript
|
||||
for the website.
|
||||
<!-- vale Crossplane.Spelling = YES -->
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
## 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/`.
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
Crossplane documentation uses [Bootstrap 5.2](https://getbootstrap.com/docs/5.2/getting-started/introduction/).
|
||||
|
||||
Bootstrap provides multiple prebuilt styles and features making CSS easier.
|
||||
|
||||
The docs import _all_ Bootstrap SCSS files and rely on Hugo and PostCSS to
|
||||
optimize the compiled CSS file.
|
||||
|
||||
The 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 >}}
|
||||
|
||||
The file `/themes/geekboot/assets/scss/docs.scss` defines all the stylesheets
|
||||
Hugo loads and compiles. Add any new styles to the `docs.scss` file to include
|
||||
them.
|
||||
|
||||
### Color themes
|
||||
Crossplane docs support a light and dark color theme that's applied via CSS
|
||||
variables.
|
||||
|
|
@ -46,108 +127,326 @@ Universal and default variables are defined in
|
|||
|
||||
Provide theme specific color overrides in
|
||||
`/themes/geekboot/assets/scss/light-mode.scss` or
|
||||
`/themes/geekboot/assets/scss/light-mode.scss`.
|
||||
`/themes/geekboot/assets/scss/dark-mode.scss`.
|
||||
|
||||
{{<hint "note" >}}
|
||||
When creating new styles rely on variables for any color function, even if both
|
||||
When creating new styles, use variables for any colors, even if both
|
||||
themes share the color.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
### SCSS compilation
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
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:
|
||||
In production, when 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.
|
||||
to organize the output CSS for another small performance boost.
|
||||
|
||||
#### How optimization works
|
||||
|
||||
Crossplane runs a
|
||||
[different Hugo CSS command](https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/themes/geekboot/layouts/partials/stylesheet-dynamic.html#L4)
|
||||
if it's in local development or production.
|
||||
|
||||
Hugo is in "production" when using `hugo` to only build HTML or with
|
||||
`hugo server --environment production`.
|
||||
|
||||
{{<hint "important" >}}
|
||||
Running Hugo in `production` mode requires the Hugo _extended_ version to
|
||||
support PostCSS.
|
||||
|
||||
Standard Hugo fails to build the documentation.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Crossplane.Spelling = NO -->
|
||||
<!-- unoptimized -->
|
||||
PurgeCSS relies on a JSON file of every HTML tag and CSS class used across the
|
||||
website and only preserves the matching CSS styles. The resulting file is around
|
||||
20x smaller than unoptimized CSS.
|
||||
<!-- vale Crossplane.Spelling = YES -->
|
||||
|
||||
Hugo generates the JSON file with the `buildStats` (or `writeStats`)
|
||||
[configuration setting](https://gohugo.io/getting-started/configuration/#configure-build)
|
||||
enabled.
|
||||
|
||||
{{<hint "important" >}}
|
||||
Some tags or classes are dynamically created or not always enabled, like light
|
||||
or dark mode.
|
||||
|
||||
Exclude these style sheets from CSS optimization with the
|
||||
`purgecss start ignore` comment.
|
||||
|
||||
For example, the Crossplane documentation ignores the `color-modes` style sheet.
|
||||
|
||||
```css
|
||||
/* purgecss start ignore */
|
||||
@import "color-modes";
|
||||
/* purgecss end ignore */
|
||||
```
|
||||
{{< /hint >}}
|
||||
|
||||
The Crossplane documentation only enables this flag during Netlify builds.
|
||||
Manually update the `config.yaml` file to enable local optimization.
|
||||
|
||||
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.
|
||||
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.
|
||||
Local development has no run-time JavaScript dependencies. To prevent
|
||||
dependencies, making JavaScript changes requires compiling and committing to git.
|
||||
|
||||
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 and dark mode color theme.
|
||||
* `tabDeepAnchor.js` rewrites anchor links inside tabs to open a tab and present
|
||||
the anchor.
|
||||
Webpack places the compiled JavaScript in `/themes/geekboot/assets/js/` and
|
||||
updates `/themes/geekboot/data/assets.json` to tell Hugo the new compiled
|
||||
JavaScript filename.
|
||||
|
||||
{{< hint "important" >}}
|
||||
The JavaScript source in `/utils/webpack/src`, newly compiled JavaScript in
|
||||
`/themes/geekboot/assets/js` and updated `/themes/geekboot/data/assets.json`
|
||||
must be in git for production and preview deploys to use the changed JavaScript.
|
||||
{{< /hint >}}
|
||||
|
||||
### JavaScript files
|
||||
* `bootstrap/` is the entire Bootstrap JavaScript library.
|
||||
* `colorMode.js` provides the ability to change the light and dark mode color
|
||||
theme.
|
||||
* `customClipboard.js` supports the `copy-lines` code box function.
|
||||
* `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/).
|
||||
* `hoverHighlight.js` provides dynamic "hover to highlight" function.
|
||||
* `slackNotify.js` creates the "Join Crossplane Slack" bubble on the home page.
|
||||
* `tabDeepAnchor.js` rewrites anchor links inside tabs to open a tab and present
|
||||
the anchor.
|
||||
|
||||
### Bootstrap JavaScript builder
|
||||
The entire [Bootstrap JavaScript
|
||||
source](https://github.com/twbs/bootstrap/tree/main/js/src) is in
|
||||
`/utils/webpack/src/js/bootstrap`.
|
||||
The `globalScripts.js` file is the entry point for Webpack. Any JavaScript
|
||||
modules or scripts must be in `globalScripts.js` to get compiled.
|
||||
|
||||
#### Building JavaScript
|
||||
|
||||
Requirements:
|
||||
* [NodeJS](https://nodejs.org/en/download) v20.1.2 or later.
|
||||
* [NPM CLI](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
|
||||
|
||||
From the `/utils/webpack` director use `npm` to install the NodeJS dependencies.
|
||||
|
||||
```shell
|
||||
cd utils/webpack
|
||||
npm install
|
||||
```
|
||||
|
||||
Building JavaScript has two options:
|
||||
1. `npm run dev`
|
||||
2. `npm run prod`
|
||||
|
||||
Using the `dev` argument doesn't optimize the JavaScript, simplifying
|
||||
debugging.
|
||||
|
||||
Using the `prod` argument optimizes the JavaScript but makes debugging more
|
||||
difficult.
|
||||
|
||||
{{<hint "important" >}}
|
||||
Always use `npm run prod` to build the compiled JavaScript to use on the
|
||||
Crossplane documentation site.
|
||||
{{< /hint >}}
|
||||
|
||||
```shell
|
||||
npm run prod
|
||||
|
||||
> prod
|
||||
> webpack --mode=production
|
||||
|
||||
assets by status 80.9 KiB [cached] 1 asset
|
||||
asset ../../data/assets.json 158 bytes [compared for emit]
|
||||
orphan modules 180 KiB [orphan] 81 modules
|
||||
runtime modules 670 bytes 3 modules
|
||||
cacheable modules 223 KiB
|
||||
modules by path ./src/js/*.js 186 KiB
|
||||
./src/js/globalScripts.js + 81 modules 181 KiB [built] [code generated]
|
||||
./src/js/colorMode.js 2.69 KiB [built] [code generated]
|
||||
./src/js/tabDeepAnchor.js 2.31 KiB [built] [code generated]
|
||||
modules by path ./node_modules/ 37.6 KiB
|
||||
./node_modules/instant.page/instantpage.js 11.4 KiB [built] [code generated]
|
||||
./node_modules/clipboard/dist/clipboard.js 26.2 KiB [built] [code generated]
|
||||
webpack 5.89.0 compiled successfully in 1248 ms
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
[Algolia](https://www.algolia.com/) provides search functionality through their
|
||||
[DocSearch](https://docsearch.algolia.com/) program.
|
||||
|
||||
{{< hint note >}}
|
||||
Crossplane docs don't use the Netlify Algolia plugin and relies on the
|
||||
[Algolia Crawler](https://www.algolia.com/doc/tools/crawler/getting-started/overview/) to
|
||||
discover new content and changes.
|
||||
{{< /hint >}}
|
||||
|
||||
## Sitemap and robots
|
||||
|
||||
Hugo generates the `robots.txt`
|
||||
[automatically](https://gohugo.io/templates/robots/).
|
||||
|
||||
For search engine discovery Crossplane uses a `sitemap.xml` file generated from
|
||||
the [`sitemap.xml` template](https://github.com/crossplane/docs/blob/master/themes/geekboot/layouts/_default/sitemap.xml).
|
||||
|
||||
## Link checking
|
||||
|
||||
Crossplane checks links with Hugo and
|
||||
[`htmltest`](https://github.com/wjdp/htmltest).
|
||||
|
||||
Hugo builds fail for any broken links in a Hugo `ref` shortcode.
|
||||
|
||||
To catch markdown links `htmltest` crawls rendered HTML and validates all
|
||||
internal links.
|
||||
|
||||
On Monday a
|
||||
[GitHub Action](https://github.com/crossplane/docs/blob/master/.github/workflows/weekly-link-checker.yml)
|
||||
runs to validate external links with `htmltest`.
|
||||
|
||||
The configuration for `htmltest` is in
|
||||
[`/utils/htmlstest`](https://github.com/crossplane/docs/blob/master/utils/htmltest/.htmltest.yml).
|
||||
|
||||
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.
|
||||
|
||||
{{<expand >}}
|
||||
```shell
|
||||
tree .
|
||||
├── content # Root for all page content
|
||||
```shell
|
||||
├── config.yaml # Hugo configuration file
|
||||
├── content # Root for all page content
|
||||
│ ├── contribute
|
||||
│ ├── knowledge-base
|
||||
│ ├── master
|
||||
│ ├── v1.12
|
||||
│ ├── v1.11
|
||||
│ └── v1.10
|
||||
├── 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
|
||||
└── vale # Files related to our Vale validation rules
|
||||
└── 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
|
||||
└── globalScripts.js # The collection of things to load on all pages
|
||||
└── hoverHighlight.js # Enables hover to highlight
|
||||
└── slackNotify.js # Tooltip to prompt user to join the community Slack
|
||||
└── tabDeepAnchor.js # Enable anchors inside tabs
|
||||
│ ├── media # Images used in docs pages
|
||||
│ ├── v1.13
|
||||
│ ├── v1.14
|
||||
│ └── v1.15
|
||||
├── hugo_stats.json # Generated by Hugo writeStats for PurgeCSS
|
||||
├── netlify.toml # Netlify configuration
|
||||
├── netlify_build.sh # Custom build script for Netlify
|
||||
├── package-lock.json # NodeJS dependency version lock
|
||||
├── package.json # NodeJS dependencies
|
||||
├── postcss.config.js # PostCSS configuration
|
||||
├── static # Legacy docs site images
|
||||
├── themes
|
||||
│ └── geekboot # The Hugo theme used by Crossplane
|
||||
│ ├── LICENSE-bootstrap
|
||||
│ ├── LICENSE-geekdoc
|
||||
│ ├── assets
|
||||
│ │ ├── js # Compiled JavaScript
|
||||
│ │ └── scss # Sytlesheets
|
||||
│ │ └── bootstrap # Unmodified Bootstrap 5.2 SCSS
|
||||
│ ├── data # Hugo mapping for JavaScript files. Autogenerated.
|
||||
│ ├── layouts # HTML template pages
|
||||
│ │ ├── 404.html # 404 page template
|
||||
│ │ ├── _default
|
||||
│ │ │ ├── _markup/ # Templates for rendering specific style components
|
||||
│ │ │ ├── baseof.html # Entrypoint template for all pages
|
||||
│ │ │ ├── list.html # List type pages, see partials/single-list.html
|
||||
│ │ │ ├── redirect.html # Provides HTML redirect functions
|
||||
│ │ │ ├── section.rss.xml # RSS feed template
|
||||
│ │ │ ├── single.html # Single type pages, see partials/single-list.html
|
||||
│ │ │ └── sitemap.xml # Sitemap template
|
||||
│ │ ├── partials # Template includes
|
||||
│ │ │ ├── analytics.html # Analytics and trackers
|
||||
│ │ │ ├── crds.html # Entrypoint for API documentation
|
||||
│ │ │ ├── docs-navbar.html # Top header links
|
||||
│ │ │ ├── docs-sidebar.html # left-side navigation menu
|
||||
│ │ │ ├── favicons.html # Favicons
|
||||
│ │ │ ├── feature-state-alert.html # Alert box for alpha/beta features
|
||||
│ │ │ ├── footer.html # Footer copyright and links
|
||||
│ │ │ ├── ga-tag.html # Google Analytics
|
||||
│ │ │ ├── google-analytics.html # Notice for GA release version
|
||||
│ │ │ ├── header.html # <head></head> content
|
||||
│ │ │ ├── icons # Icons from fontawesome and Crossplane specific
|
||||
│ │ │ ├── icons.html # SVG includes common enough to be on every page
|
||||
│ │ │ ├── left-nav.html # Left-hand navigation
|
||||
│ │ │ ├── master-version-alert.html # Alert box for the master version
|
||||
│ │ │ ├── mermaid.html # Styling and JavaScript for mermaid diagrams
|
||||
│ │ │ ├── meta-common.html # <meta> tags used on all pages
|
||||
│ │ │ ├── ms-clarity.html # Microsoft Clarity tags
|
||||
│ │ │ ├── old-version-alert.html # Alert box for versions that aren't the latest
|
||||
│ │ │ ├── redirect.html # HTML meta redirect
|
||||
│ │ │ ├── release-notes.html # Release note summary page generator
|
||||
│ │ │ ├── rollworks.html # Rollworks analytics tags
|
||||
│ │ │ ├── scripts.html # Global JavaScript includes
|
||||
│ │ │ ├── search-button.html # Algolia search button
|
||||
│ │ │ ├── sidebar # Static links in the left-side nav
|
||||
│ │ │ ├── single-list.html # Template used by all single and list type pages
|
||||
│ │ │ ├── skippy.html # Shift the page when the target is an anchor link
|
||||
│ │ │ ├── social.html # Social media data includes
|
||||
│ │ │ ├── stylesheet-cached.html # Static CSS that never changes
|
||||
│ │ │ ├── stylesheet-dynamic.html # Dynamic CSS that may change between pages
|
||||
│ │ │ ├── toc.html # Table of contents modifications
|
||||
│ │ │ ├── utils # Utils imported from Geekdoc theme
|
||||
│ │ │ └── version-dropdown-menu.html # Version dropdown menu
|
||||
│ │ └── shortcodes
|
||||
│ │ ├── check.html # Produce and style a Checkmark
|
||||
│ │ ├── editCode.html # Code box with editable field
|
||||
│ │ ├── expand.html # Expand button
|
||||
│ │ ├── getCRDs.html # Generate API pages
|
||||
│ │ ├── hint.html # Hint boxes
|
||||
│ │ ├── hover.html # Hover to highlight
|
||||
│ │ ├── img.html # Image optimizer
|
||||
│ │ ├── include.html # Include an external file
|
||||
│ │ ├── markdown.html # Run content through the markdown engine again
|
||||
│ │ ├── param.html # Import from Bootstrap theme
|
||||
│ │ ├── partial.html # Import from Bootstrap theme
|
||||
│ │ ├── placeholder.html # Import from Bootstrap theme
|
||||
│ │ ├── propertylist.html # Import from Bootstrap theme
|
||||
│ │ ├── tab.html # Individual Tab. Related to tabs.html
|
||||
│ │ ├── table.html # Apply bootstrap styles to markdown tables
|
||||
│ │ ├── tabs.html # Tab builder, related to tab.html
|
||||
│ │ ├── url.html # Create a download link to a file. Used by the APIs
|
||||
│ │ └── year.html # Print the current year
|
||||
│ └── static # Static global image files
|
||||
└── utils # Scripts and tools related to the docs
|
||||
├── htmltest # htmltest link checker
|
||||
├── vale # Vale linter
|
||||
│ └── styles
|
||||
│ ├── Crossplane # Crossplane spelling exceptions
|
||||
│ ├── Google # Google's Vale rules
|
||||
│ ├── Microsoft # Microsoft's Vale rules
|
||||
│ ├── alex # Write inclusive language
|
||||
│ ├── gitlab # Gitlab's Vale rules
|
||||
│ ├── proselint # Write better
|
||||
│ └── write-good # Write better
|
||||
└── webpack # JavaScript tools
|
||||
├── package-lock.json # NodeJS dependency version lock
|
||||
├── package.json # NodeJS dependencies
|
||||
├── src
|
||||
│ └── js
|
||||
│ ├── bootstrap/ # Unmodified Bootstrap JavaScript
|
||||
│ ├── colorMode.js # Color mode switcher
|
||||
│ ├── customClipboard.js # Custom copy-to-clipboard tool
|
||||
│ ├── globalScripts.js # Point of entry for all scripts compiled by Webpack
|
||||
│ ├── hoverHighlight.js # Hover to highlight
|
||||
│ ├── slackNotify.js # "Join Crossplane Slack" bubble
|
||||
│ └── tabDeepAnchor.js # Link inside a tab
|
||||
└── webpack.config.js
|
||||
```
|
||||
{{</expand>}}
|
||||
|
|
@ -52,8 +52,7 @@ Crossplane uses the following Vale styles:
|
|||
* [Google](https://github.com/errata-ai/google) - for the [Google developer documentation style guide](https://developers.google.com/style).
|
||||
* [Microsoft](https://github.com/errata-ai/Microsoft) - for the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
|
||||
* [proselint](https://github.com/errata-ai/proselint) - for higher quality writing.
|
||||
* [Upbound](https://github.com/upbound/vale/tree/main/styles/Upbound) - for
|
||||
customized terms and preventing corporate jargon.
|
||||
* [Crossplane](https://github.com/crossplane/docs/tree/master/utils/vale/styles/Crossplane) - spelling exceptions for Kubernetes and Crossplane related words.
|
||||
* [write-good](https://github.com/errata-ai/write-good) - for higher quality writing.
|
||||
|
||||
{{<hint "warning" >}}
|
||||
|
|
@ -120,7 +119,7 @@ Vale back on.
|
|||
|
||||
For example,
|
||||
|
||||
```text
|
||||
```plaintext
|
||||
<!-- vale off -->
|
||||
<!-- turn off vale checking for this example -->
|
||||
The following example will use passive voice and lowercase crossplane. Do not do this.
|
||||
|
|
@ -138,7 +137,7 @@ Do not turn off rules without good reasons.
|
|||
<!-- vale Microsoft.Contractions = YES -->
|
||||
|
||||
For example,
|
||||
```text
|
||||
```plaintext
|
||||
<!-- vale Microsoft.Contractions = NO -->
|
||||
<!-- turn off contractions for the example -->
|
||||
Do not turn off rules without good reasons.
|
||||
|
|
@ -149,3 +148,20 @@ Do not turn off rules without good reasons.
|
|||
Vale requires capitalization for `YES` and `NO` and a space around `=`.
|
||||
{{</hint >}}
|
||||
|
||||
## Vale settings
|
||||
|
||||
The Vale configuration for the repository is in
|
||||
[utils/vale/vale.ini](https://github.com/crossplane/docs/blob/master/utils/vale/.vale.ini).
|
||||
|
||||
{{< hint "note" >}}
|
||||
The `vale.ini` file is a Vale configuration file. Read the Vale documentation
|
||||
for more information about the `vale.ini` file.
|
||||
{{< /hint >}}
|
||||
|
||||
Some imported Vale styles don't apply or duplicate other rules. Disable
|
||||
individual rules inside the `vale.ini` file.
|
||||
|
||||
For example Google and Microsoft rules both cover the use of first person words
|
||||
like `I`. The docs `vale.ini` disables the
|
||||
[Microsoft rule](https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/utils/vale/.vale.ini#L42)
|
||||
to prevent duplicate errors.
|
||||
23
netlify.toml
23
netlify.toml
|
|
@ -1,11 +1,27 @@
|
|||
# Read the Netlify docs for details:
|
||||
# https://docs.netlify.com/configure-builds/file-based-configuration/
|
||||
#
|
||||
#
|
||||
# Build commands. Logic for previews vs prod are handled inside netlify_build.sh
|
||||
[context.deploy-preview]
|
||||
command = "bash netlify_build.sh"
|
||||
|
||||
[context.production]
|
||||
command = "bash netlify_build.sh"
|
||||
|
||||
[build]
|
||||
base = "/"
|
||||
publish = "public/"
|
||||
command = "bash netlify_build.sh"
|
||||
|
||||
# The version of Hugo to use for the Netlify build.
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.119.0"
|
||||
|
||||
#
|
||||
# The following are Netlify redirects for moved docs pages
|
||||
# https://docs.netlify.com/configure-builds/file-based-configuration/#redirects
|
||||
#
|
||||
[[redirects]]
|
||||
from = "/docs/*"
|
||||
to = "/:splat"
|
||||
|
|
@ -17,7 +33,6 @@ from = "/v1.12/*"
|
|||
to = "/latest/:splat"
|
||||
status = 302
|
||||
|
||||
# Redirects for EOL versions
|
||||
[[redirects]]
|
||||
from = "/v1.11/*"
|
||||
to = "/latest/:splat"
|
||||
|
|
@ -55,12 +70,6 @@ from = "/knowledge-base/install/**"
|
|||
to = "/latest/software/"
|
||||
status = 302
|
||||
|
||||
[context.deploy-preview]
|
||||
command = "bash netlify_build.sh"
|
||||
|
||||
[context.production]
|
||||
command = "bash netlify_build.sh"
|
||||
|
||||
# Use [dev] to set configuration overrides for local
|
||||
# development environments run using Netlify Dev - except
|
||||
# for environment variables. Environment variables for Netlify
|
||||
|
|
|
|||
|
|
@ -1,16 +1,30 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
# Which which version is the "Latest"?
|
||||
LATEST_VER="1.15"
|
||||
|
||||
# Make a copy of /content/$LATEST_VER to the directory /latest
|
||||
# Search indexing only points to /latest, this prevents broken or out of date
|
||||
# search results
|
||||
cp -R content/v$LATEST_VER content/latest
|
||||
|
||||
# Set the `version` front matter to prevent redirect issues with the version
|
||||
# drop-down menu.
|
||||
sed -i "s/^\s*version: \"$LATEST_VER\"//g" content/latest/_index.md
|
||||
|
||||
# Enable Hugo writeStats to enable PurgeCSS optimizations.
|
||||
# docs: https://gohugo.io/getting-started/configuration/#configure-build
|
||||
sed -i 's/# writeStats: true/writeStats: true/g' config.yaml
|
||||
cat config.yaml
|
||||
|
||||
# $CONTEXT is a Netlify environmental variable.
|
||||
# https://docs.netlify.com/configure-builds/environment-variables/#build-metadata
|
||||
|
||||
# For production set the baseURL to be the docs URL
|
||||
if [ "$CONTEXT" = "production" ]; then
|
||||
hugo --minify --baseURL https://docs.crossplane.io/
|
||||
|
||||
# For any other context use the Netlify deploy URL.
|
||||
elif [ "$CONTEXT" = "branch-deploy" ]; then
|
||||
echo "Building branch deploy with URL $DEPLOY_PRIME_URL"
|
||||
hugo --minify --baseURL $DEPLOY_PRIME_URL
|
||||
|
|
|
|||
|
|
@ -1,9 +1,17 @@
|
|||
// LightningCSS settings
|
||||
// https://lightningcss.dev/
|
||||
//
|
||||
// Support browsers with at least 0.25% usage from broswerlist: https://browserslist.dev/?q=bGFzdCAyIHZlcnNpb25z
|
||||
const postcssLightningcss = require("postcss-lightningcss")({
|
||||
browsers: ">= .25%",
|
||||
lightningcssOptions: {
|
||||
}
|
||||
});
|
||||
|
||||
// PurgeCSS settings
|
||||
// https://purgecss.com/
|
||||
//
|
||||
// Load hugo_stats.json to know what elements are in use
|
||||
const purgecss = require('@fullhuman/postcss-purgecss')({
|
||||
content: ['./hugo_stats.json'],
|
||||
variables: true,
|
||||
|
|
@ -18,6 +26,10 @@ const purgecss = require('@fullhuman/postcss-purgecss')({
|
|||
safelist: []
|
||||
});
|
||||
|
||||
// PostCSS Media sort
|
||||
// https://github.com/yunusga/postcss-sort-media-queries
|
||||
//
|
||||
// Sort CSS to prioritize desktop users
|
||||
const mediasort = require('postcss-sort-media-queries')({
|
||||
sort: 'desktop-first'
|
||||
});
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
Algolia
|
||||
Bootstrap
|
||||
CC-BY
|
||||
CNCF
|
||||
Commonmark
|
||||
DockerHub
|
||||
DocSearch
|
||||
Geekdocs
|
||||
Goldmark
|
||||
Grammarly
|
||||
|
|
@ -11,6 +13,7 @@ HashiCorp
|
|||
instant.page
|
||||
Kustomize
|
||||
Netlify
|
||||
NodeJS
|
||||
NPM
|
||||
OpenAPI
|
||||
OpenAPIv3
|
||||
|
|
|
|||
|
|
@ -4,6 +4,12 @@
|
|||
* Licensed under MIT (https://github.com/coliff/dark-mode-switch/blob/main/LICENSE)
|
||||
*/
|
||||
|
||||
/*
|
||||
*
|
||||
* Controls the dark mode/light mode switcher and saves a cookie to remember the
|
||||
* user preference.
|
||||
*/
|
||||
|
||||
(() => {
|
||||
var darkSwitch = document.getElementById("darkSwitch");
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,11 @@
|
|||
// Customize clipboard.js
|
||||
import * as ClipboardJS from 'clipboard';
|
||||
|
||||
/*
|
||||
* Extends clipboard.js to support passing line numbers to copy instead of a
|
||||
* whole code box.
|
||||
*/
|
||||
|
||||
// copy API links to the clipboard
|
||||
const crdURLCopier = new ClipboardJS('.kind-link');
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,14 @@
|
|||
// The collection of things to load on all pages
|
||||
|
||||
// Color mode switcher
|
||||
import ColorMode from './colorMode';
|
||||
|
||||
// Link pre-fetcher
|
||||
// https://instant.page/
|
||||
import 'instant.page';
|
||||
|
||||
|
||||
// Bootstrap JS libraries in use.
|
||||
// IF a new Bootstrap feature requires JS, add it here.
|
||||
import './bootstrap/src/base-component';
|
||||
import './bootstrap/src/button';
|
||||
import './bootstrap/src/collapse';
|
||||
|
|
@ -12,7 +18,14 @@ import './bootstrap/src/scrollspy';
|
|||
import './bootstrap/src/tab';
|
||||
import './bootstrap/src/offcanvas';
|
||||
|
||||
// If a link is to an anchor inside a tab, open the tab and go to the anchor
|
||||
import './tabDeepAnchor.js';
|
||||
|
||||
// Customize the clipboard to support the `copy-lines` function
|
||||
import './customClipboard.js';
|
||||
|
||||
// Hover to highlight function
|
||||
import './hoverHighlight.js';
|
||||
|
||||
// "Join Slack" notification bubble
|
||||
import './slackNotify.js';
|
||||
|
|
@ -1,3 +1,10 @@
|
|||
/*
|
||||
* Create the hover to highlight function.
|
||||
*
|
||||
* Finds the code box matching the label and updates the code box to add a
|
||||
* highlight function.
|
||||
*/
|
||||
|
||||
export function getKeywords(){
|
||||
var keywordList = document.getElementsByTagName("highlight-term")
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
/*
|
||||
* Create a PopperJS popover for the Join Slack notifications.
|
||||
*/
|
||||
|
||||
import { createPopper } from '@popperjs/core';
|
||||
|
||||
const slackIcon = document.querySelector('#slack');
|
||||
|
|
|
|||
Loading…
Reference in New Issue