@@ -18,7 +18,7 @@ The Crossplane docs tools consist of:
1818
1919## Netlify
2020
21- Builds for production deploys and PR previews are automatically done by Netlify.
21+ Builds for production deploys and PR previews are automatically done by Netlify.
2222
2323{{< hint "note" >}}
2424The CNCF controls Netlify access.
@@ -31,7 +31,7 @@ Settings inside the `netlify.toml` file override any settings in the Netlify web
3131interface.
3232
3333The
34- [ ` build ` ] ( https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/netlify.toml#L1 )
34+ [ ` build ` ] ( https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/netlify.toml#L1 )
3535directive defines what Netlify does to build the site.
3636
3737The
4242[ ` redirects ` ] ( https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/netlify.toml#L9 )
4343are server side HTTP redirects for moved pages.
4444
45- The [ Netlify documentation] ( https://docs.netlify.com/configure-builds/file-based-configuration/ )
45+ The [ Netlify documentation] ( https://docs.netlify.com/configure-builds/file-based-configuration/ )
4646has more information about configuring ` netlify.toml ` .
4747
4848Netlify automatically detects the
@@ -51,32 +51,32 @@ file and loads the listed NodeJS dependencies.
5151
5252<!-- vale off -->
5353### netlify_build.sh
54- <!-- vale on -->
54+ <!-- vale on -->
5555
5656During a build Netlify runs the Bash script
57- [ ` netlify_build.sh ` ] ( https://github.com/crossplane/docs/blob/master/netlify_build.sh ) .
57+ [ ` netlify_build.sh ` ] ( https://github.com/crossplane/docs/blob/master/netlify_build.sh ) .
5858
59- The script creates a new docs section called ` latest ` and copies the defined
59+ The script creates a new docs section called ` latest ` and copies the defined
6060` LATEST_VER ` to ` /latest ` .
6161
62- Next the script enables ` writeStats ` in the Hugo configuration file.
62+ Next the script enables ` writeStats ` in the Hugo configuration file.
6363
64- Then, using the Netlify ` $CONTEXT `
64+ Then, using the Netlify ` $CONTEXT `
6565[ environmental variable] ( https://docs.netlify.com/configure-builds/environment-variables/#build-metadata )
6666Hugo runs, defining the [ ` BaseURL ` ] ( https://gohugo.io/methods/site/baseurl/ ) to
6767use for generating internal links.
6868
6969## Hugo
70- Crossplane uses [ Hugo] ( https://gohugo.io/ ) , a static site generator.
70+ Crossplane uses [ Hugo] ( https://gohugo.io/ ) , a static site generator.
7171
7272Hugo combines HTML templates, markdown content and generates static HTML
73- content.
73+ content.
7474
7575{{<hint "note" >}}
7676The Hugo web server is only used for local development. Crossplane documentation
77- uses Netlify for hosting.
77+ uses Netlify for hosting.
7878
79- Hugo only acts as an HTML compiler.
79+ Hugo only acts as an HTML compiler.
8080{{< /hint >}}
8181
8282Hugo influences the directory structure of the repository.
@@ -101,21 +101,21 @@ The docs import _all_ Bootstrap SCSS files and rely on Hugo and PostCSS to
101101optimize the compiled CSS file.
102102
103103The unmodified Bootstrap SCSS files are in
104- ` /themes/geekboot/assets/scss/bootstrap/ ` .
104+ ` /themes/geekboot/assets/scss/bootstrap/ ` .
105105
106- Any docs-specific overrides are in per-element SCSS files located one directory
106+ Any docs-specific overrides are in per-element SCSS files located one directory
107107higher in ` /themes/geekboot/assets/scss/ ` .
108108
109109{{<hint "important" >}}
110110Don't edit the original Bootstrap stylesheets. It makes the ability to
111111upgrade to future Bootstrap versions difficult or impossible.
112112{{< /hint >}}
113113
114- The file ` /themes/geekboot/assets/scss/docs.scss ` defines all the stylesheets
114+ The file ` /themes/geekboot/assets/scss/docs.scss ` defines all the stylesheets
115115Hugo loads and compiles. Add any new styles to the ` docs.scss ` file to include
116116them.
117117
118- ### Color themes
118+ ### Color themes
119119Crossplane docs support a light and dark color theme that's applied via CSS
120120variables.
121121
@@ -143,35 +143,35 @@ Hugo compiles the SCSS to CSS. Local development doesn't require SCSS installed.
143143For local development (when using ` hugo server ` ) Hugo compiles SCSS without
144144any optimizations.
145145
146- In production, when publishing on Netlify or using
147- ` hugo server --environment production ` , Hugo compiles SCSS and optimizes the
148- CSS with [ PostCSS] ( https://postcss.org/ ) .
146+ In production, when publishing on Netlify or using
147+ ` hugo server --environment production ` , Hugo compiles SCSS and optimizes the
148+ CSS with [ PostCSS] ( https://postcss.org/ ) .
149149
150150
151- The PostCSS configuration is in ` /postcss.config.js ` .
151+ The PostCSS configuration is in ` /postcss.config.js ` .
152152
153153The optimizations includes:
154154* [ postcss-lightningcss] ( https://github.com/onigoetz/postcss-lightningcss ) - for
155155 building, minimizing and generating a source map.
156156* [ PurgeCSS] ( https://purgecss.com/plugins/postcss.html ) - removes unused styles
157- to reduce the CSS file size.
158- * [ postcss-sort-media-queries] ( https://github.com/yunusga/postcss-sort-media-queries ) -
157+ to reduce the CSS file size.
158+ * [ postcss-sort-media-queries] ( https://github.com/yunusga/postcss-sort-media-queries ) -
159159to organize the output CSS for another small performance boost.
160160
161161#### How optimization works
162162
163- Crossplane runs a
164- [ different Hugo CSS command] ( https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/themes/geekboot/layouts/partials/stylesheet-dynamic.html#L4 )
165- if it's in local development or production.
163+ Crossplane runs a
164+ [ different Hugo CSS command] ( https://github.com/crossplane/docs/blob/3e9e10671c32e368f5381d83e406e16bc38c93bc/themes/geekboot/layouts/partials/stylesheet-dynamic.html#L4 )
165+ if it's in local development or production.
166166
167- Hugo is in "production" when using ` hugo ` to only build HTML or with
167+ Hugo is in "production" when using ` hugo ` to only build HTML or with
168168` hugo server --environment production ` .
169169
170170{{<hint "important" >}}
171171Running Hugo in ` production ` mode requires the Hugo _ extended_ version to
172172support PostCSS.
173173
174- Standard Hugo fails to build the documentation.
174+ Standard Hugo fails to build the documentation.
175175{{< /hint >}}
176176
177177<!-- vale Crossplane.Spelling = NO -->
@@ -182,15 +182,15 @@ website and only preserves the matching CSS styles. The resulting file is around
182182<!-- vale Crossplane.Spelling = YES -->
183183
184184Hugo generates the JSON file with the ` buildStats ` (or ` writeStats ` )
185- [ configuration setting] ( https://gohugo.io/getting-started/configuration/#configure-build )
185+ [ configuration setting] ( https://gohugo.io/getting-started/configuration/#configure-build )
186186enabled.
187187
188188{{<hint "important" >}}
189189Some tags or classes are dynamically created or not always enabled, like light
190- or dark mode.
190+ or dark mode.
191191
192192Exclude these style sheets from CSS optimization with the
193- ` purgecss start ignore ` comment.
193+ ` purgecss start ignore ` comment.
194194
195195For example, the Crossplane documentation ignores the ` color-modes ` style sheet.
196196
@@ -210,9 +210,9 @@ Optimizing CSS locally with PostCSS requires installing extra packages.
210210* NPM packages defined in ` /package.json ` with ` npm install ` .
211211
212212## JavaScript
213- A goal of the documentation website is to use as little JavaScript as possible.
214- Unless the script provides a significant improvement in performance, capability
215- or user experience.
213+ A goal of the documentation website is to use as little JavaScript as possible.
214+ Unless the script provides a significant improvement in performance, capability
215+ or user experience.
216216
217217Local development has no run-time JavaScript dependencies. To prevent
218218dependencies, making JavaScript changes requires compiling and committing to git.
@@ -226,7 +226,7 @@ JavaScript filename.
226226
227227{{< hint "important" >}}
228228The JavaScript source in ` /utils/webpack/src ` , newly compiled JavaScript in
229- ` /themes/geekboot/assets/js ` and updated ` /themes/geekboot/data/assets.json `
229+ ` /themes/geekboot/assets/js ` and updated ` /themes/geekboot/data/assets.json `
230230must be in git for production and preview deploys to use the changed JavaScript.
231231{{< /hint >}}
232232
@@ -238,13 +238,13 @@ must be in git for production and preview deploys to use the changed JavaScript.
238238* ` globalScripts.js ` is the point of entry for Webpack to determine all
239239 dependencies. This bundles [ instant.page] ( https://instant.page/ ) and
240240 [ Bootstrap's JavaScript] ( https://getbootstrap.com/docs/5.2/getting-started/javascript/ ) .
241- * ` hoverHighlight.js ` provides dynamic "hover to highlight" function.
241+ * ` hoverHighlight.js ` provides dynamic "hover to highlight" function.
242242* ` slackNotify.js ` creates the "Join Crossplane Slack" bubble on the home page.
243243* ` tabDeepAnchor.js ` rewrites anchor links inside tabs to open a tab and present
244- the anchor.
245-
244+ the anchor.
245+
246246The ` globalScripts.js ` file is the entry point for Webpack. Any JavaScript
247- modules or scripts must be in ` globalScripts.js ` to get compiled.
247+ modules or scripts must be in ` globalScripts.js ` to get compiled.
248248
249249#### Building JavaScript
250250
@@ -260,14 +260,14 @@ npm install
260260```
261261
262262Building JavaScript has two options:
263- 1 . ` npm run dev `
263+ 1 . ` npm run dev `
2642642 . ` npm run prod `
265265
266266Using the ` dev ` argument doesn't optimize the JavaScript, simplifying
267- debugging.
267+ debugging.
268268
269269Using the ` prod ` argument optimizes the JavaScript but makes debugging more
270- difficult.
270+ difficult.
271271
272272{{<hint "important" >}}
273273Always use ` npm run prod ` to build the compiled JavaScript to use on the
@@ -301,14 +301,14 @@ webpack 5.89.0 compiled successfully in 1248 ms
301301[ DocSearch] ( https://docsearch.algolia.com/ ) program.
302302
303303{{< hint note >}}
304- Crossplane docs don't use the Netlify Algolia plugin and relies on the
304+ Crossplane docs don't use the Netlify Algolia plugin and relies on the
305305[ Algolia Crawler] ( https://www.algolia.com/doc/tools/crawler/getting-started/overview/ ) to
306306discover new content and changes.
307307{{< /hint >}}
308308
309309## Sitemap and robots
310310
311- Hugo generates the ` robots.txt `
311+ Hugo generates the ` robots.txt `
312312[ automatically] ( https://gohugo.io/templates/robots/ ) .
313313
314314For search engine discovery Crossplane uses a ` sitemap.xml ` file generated from
@@ -322,21 +322,21 @@ Crossplane checks links with Hugo and
322322Hugo builds fail for any broken links in a Hugo ` ref ` shortcode.
323323
324324To catch markdown links ` htmltest ` crawls rendered HTML and validates all
325- internal links.
325+ internal links.
326326
327327On Monday a
328- [ GitHub Action] ( https://github.com/crossplane/docs/blob/master/.github/workflows/weekly-link-checker.yml )
328+ [ GitHub Action] ( https://github.com/crossplane/docs/blob/master/.github/workflows/weekly-link-checker.yml )
329329runs to validate external links with ` htmltest ` .
330330
331- The configuration for ` htmltest ` is in
332- [ ` /utils/htmlstest ` ] ( https://github.com/crossplane/docs/blob/master/utils/htmltest/.htmltest.yml ) .
331+ The configuration for ` htmltest ` is in
332+ [ ` /utils/htmlstest ` ] ( https://github.com/crossplane/docs/blob/master/utils/htmltest/.htmltest.yml ) .
333333
334334
335335## Annotated website tree
336336Expand the tab below to see an annotated ` tree ` output of the website repository.
337337
338338{{<expand >}}
339- ``` shell
339+ ``` shell
340340├── config.yaml # Hugo configuration file
341341├── content # Root for all page content
342342│ ├── contribute
@@ -352,7 +352,7 @@ Expand the tab below to see an annotated `tree` output of the website repository
352352├── package.json # NodeJS dependencies
353353├── postcss.config.js # PostCSS configuration
354354├── static # Legacy docs site images
355- ├── themes
355+ ├── themes
356356│ └── geekboot # The Hugo theme used by Crossplane
357357│ ├── LICENSE-bootstrap
358358│ ├── LICENSE-geekdoc
@@ -388,12 +388,10 @@ Expand the tab below to see an annotated `tree` output of the website repository
388388│ │ │ ├── master-version-alert.html # Alert box for the master version
389389│ │ │ ├── mermaid.html # Styling and JavaScript for mermaid diagrams
390390│ │ │ ├── meta-common.html # <meta> tags used on all pages
391- │ │ │ ├── ms-clarity.html # Microsoft Clarity tags
392391│ │ │ ├── old-version-alert.html # Alert box for versions that aren't the latest
393392│ │ │ ├── preview-version-alert.html # Alert box for preview versions
394393│ │ │ ├── redirect.html # HTML meta redirect
395394│ │ │ ├── release-notes.html # Release note summary page generator
396- │ │ │ ├── rollworks.html # Rollworks analytics tags
397395│ │ │ ├── scripts.html # Global JavaScript includes
398396│ │ │ ├── search-button.html # Algolia search button
399397│ │ │ ├── sidebar # Static links in the left-side nav
@@ -411,7 +409,7 @@ Expand the tab below to see an annotated `tree` output of the website repository
411409│ │ ├── expand.html # Expand button
412410│ │ ├── getCRDs.html # Generate API pages
413411│ │ ├── hint.html # Hint boxes
414- │ │ ├── hover.html # Hover to highlight
412+ │ │ ├── hover.html # Hover to highlight
415413│ │ ├── img.html # Image optimizer
416414│ │ ├── include.html # Include an external file
417415│ │ ├── markdown.html # Run content through the markdown engine again
@@ -439,13 +437,13 @@ Expand the tab below to see an annotated `tree` output of the website repository
439437 └── webpack # JavaScript tools
440438 ├── package-lock.json # NodeJS dependency version lock
441439 ├── package.json # NodeJS dependencies
442- ├── src
440+ ├── src
443441 │ └── js
444442 │ ├── bootstrap/ # Unmodified Bootstrap JavaScript
445443 │ ├── colorMode.js # Color mode switcher
446444 │ ├── customClipboard.js # Custom copy-to-clipboard tool
447445 │ ├── globalScripts.js # Point of entry for all scripts compiled by Webpack
448- │ ├── hoverHighlight.js # Hover to highlight
446+ │ ├── hoverHighlight.js # Hover to highlight
449447 │ ├── slackNotify.js # "Join Crossplane Slack" bubble
450448 │ └── tabDeepAnchor.js # Link inside a tab
451449 └── webpack.config.js
0 commit comments