diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 2d8ed34148..9ae05d8c5b 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ -blank_issues_enabled: false +blank_issues_enabled: true contact_links: - name: SUPPORT, ISSUES, and TROUBLESHOOTING url: https://github.com/google/docsy/discussions diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index e94081f037..18c2711b37 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -25,4 +25,7 @@ jobs: cache: npm cache-dependency-path: package.json - run: npm install --omit=optional - - run: npm run test:all + - if: runner.os != 'Windows' + run: npm run test:all + - if: runner.os == 'Windows' + run: npm run ci:prepare && npm run cd:docs build && npm run ci:post diff --git a/.markdown-link-check.json b/.markdown-link-check.json deleted file mode 100644 index 9dfad0352c..0000000000 --- a/.markdown-link-check.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "^http://localhost" - }, - { - "pattern": "^https://badges.netlify.com/api/docsydocs.svg\\?branch=main" - }, - { - "pattern": "^https://docs.npmjs.com/cli/v10/using-npm/scripts#prepare-and-prepublish" - }, - { - "pattern": "^#070$" - } - ], - "timeout": "3s", - "retryOn429": true, - "aliveStatusCodes": [200, 206] -} diff --git a/.prettierignore b/.prettierignore index f112941105..e69de29bb2 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,6 +0,0 @@ -.editorconfig -.gitattributes -.gitignore -.nvmrc -.prettierignore -.s3deploy.yml diff --git a/.s3deploy.yml b/.s3deploy.yml deleted file mode 100644 index c8985e0279..0000000000 --- a/.s3deploy.yml +++ /dev/null @@ -1,14 +0,0 @@ -routes: - - route: "^.+\\.(js|css|svg|ttf)$" - # cache static assets for 20 years - headers: - Cache-Control: "max-age=630720000, no-transform, public" - gzip: true - - route: "^.+\\.(png|jpg)$" - headers: - Cache-Control: "max-age=630720000, no-transform, public" - gzip: true - - route: "^.+\\.(html|xml|json)$" - gzip: true - - \ No newline at end of file diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 3e4a324385..a4fedb3a9e 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -2,5 +2,15 @@ { "version": "0.2", "caseSensitive": true, - "words": ["Docsy", "hugo", "shortcode", "shortcodes", "warnf"] + "words": [ + "Docsy", + "errorf", + "hugo", + "shortcode", + "shortcodes", + "tabpane", + "upvote", + "warnf", + "relref" + ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index e751b5c6e3..7172e349b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,16 +18,15 @@ Useful links: [releases]: https://github.com/google/docsy/releases [tags]: https://github.com/google/docsy/tags -## 0.9.2 or 0.10.0 +## 0.12.1 or 0.13.0 -> ### UNRELEASED: this planned version is still under development +> **UNRELEASED: this planned version is still under development** For the full list of changes, see the [0.x.y] release notes. **Breaking changes**: -- Removed shortcode `card-code` that was [deprecated in 0.7.0](#070); use - shortcode `card` with named parameter `code=true` instead. +- ... **New**: @@ -35,6 +34,122 @@ For the full list of changes, see the [0.x.y] release notes. [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y +## 0.12.0 + +For the full list of changes, see the [0.12.0] release notes. + +**Breaking changes**: + +- Renames the default Docsy heading render hook and heading self-link partials. + This is a breaking change only if your project uses this feature. For details, + see [Heading self links][] ([#2223]). +- Relocates and adapts layouts in response to Hugo's [new template system][]. + For details, see [Adapt to new template system in Hugo v0.146.0 #2243][#2243]. +- **IMPORTANT**: if your project overrides any of the layout files mentioned in + [#2243], then apply the same name changes in your project files. In + particular, note that: + - Taxonomy-related layout files: names have been _swapped_, and `terms.html` + is now singular ([#2257]): + - Renames `_default/taxonomy.html` to `term.html` (singular) + - Renames `_default/terms.html` to `taxonomy.html` + - Renames `layouts/**/content.html` by adding a `_td-` filename prefix + ([#2259]). + +[#2257]: https://github.com/google/docsy/pull/2257 +[#2259]: https://github.com/google/docsy/pull/2259 +[new template system]: https://gohugo.io/templates/new-templatesystem-overview/ + +**Potential breaking changes**: + +- Removes shortcode `figure`, hugo's built-in shortcode `figure` can/will be + used instead. + +**New**: + +- **[Breadcrumb navigation]** support has been enhanced and adjusted: + - You can now disable breadcrumbs for an entire project, or individual pages + or sections by setting `ui.breadcrumb_disable` to true. For details, see + [Breadcrumb navigation][]. + - **Blog** pages now also have breadcrumbs by default ([#1788]). + - Index-page single-element breadcrumb lists are hidden by default ([#2160]). +- Support for a [_td-content-after-header.html] page-content render hook, which + can be [content type][] specific ([#2192]). For details, see the [User + Guide][before-page-content]. + +**Other changes**: + +- **Blog** section index page content and title used to be ignored, they are now + displayed ([#1787]). To recover the old behavior use the following style + override: `.td-section.td-blog .td-content { display: none; }`. +- Adds a `comment` shortcode, as a drop-in replacement for the one removed from + Hugo. + +[0.12.0]: https://github.com/google/docsy/releases/v0.12.0 +[#1787]: https://github.com/google/docsy/issues/1787 +[#1788]: https://github.com/google/docsy/issues/1788 +[#2160]: https://github.com/google/docsy/pull/2160 +[#2192]: https://github.com/google/docsy/pull/2192 +[#2223]: https://github.com/google/docsy/pull/2223 +[#2243]: https://github.com/google/docsy/pull/2243 +[before-page-content]: + https://www.docsy.dev/docs/adding-content/lookandfeel/#before-page-content +[Breadcrumb navigation]: + https://www.docsy.dev/docs/adding-content/navigation/#breadcrumb-navigation +[content type]: https://gohugo.io/quick-reference/glossary/#content-type +[Heading self links]: + https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links +[_td-content-after-header.html]: + https://github.com/google/docsy/blob/main/layouts/_td-content-after-header.html + +## 0.11.0 + +For the full list of changes, see the [0.11.0] release notes. + +**New**: + +- Support for Right-To-Left (RLT) languages is reintroduced via [Bootstrap's + support for RTL][bs-rtl]. For details, see [Right-to-left languages][rtl]. +- The URL to your project's contribution guidelines is configurable. For + details, see [Adding a community page]. +- When a section's sidebar entries are truncated because there are more than + [params.ui.sidebar_menu_truncate] section entries, a warning is issued. + +[0.11.0]: https://github.com/google/docsy/releases/v0.11.0 +[bs-rtl]: https://getbootstrap.com/docs/5.3/getting-started/rtl/ +[Adding a community page]: + https://www.docsy.dev/docs/adding-content/content/#adding-a-community-page +[params.ui.sidebar_menu_truncate]: + https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options +[rtl]: https://www.docsy.dev/docs/language/#right-to-left-languages + +## 0.10.0 + +For an introduction to this release, see the [0.10.0 release report]. For the +full list of changes, see the [0.10.0] release notes. + +**New**: color themes and dark-mode support! For details, see [Color themes and +dark-mode support][dark-mode]. + +**Breaking changes**: + +- Removes shortcode `card-code` that was [deprecated in 0.7.0](#070); use + shortcode `card` with named parameter `code=true` instead. +- The following SCSS variables are inlined in favor of dark-mode compatible + styling: `$border-color`, `$td-sidebar-tree-root-color`, + `$td-sidebar-bg-color`, `$td-sidebar-border-color` ([#1952]) + +**Style changes** (potentially breaking): + +- The style of various shortcode and elements have been adjusted so that they + are compatible with light/dark mode. For details see, **Important style + changes** in [Color themes and dark-mode support][dark-mode]. + +[#1952]: https://github.com/google/docsy/pull/1952 +[0.10.0]: https://github.com/google/docsy/releases/v0.10.0 +[0.10.0 release report]: https://www.docsy.dev/blog/2024/0.10.0/ +[dark-mode]: + https://www.docsy.dev/blog/2024/0.10.0/#color-themes-and-dark-mode-support + ## 0.9.1 Patch release. For details, see [0.9.1]. @@ -64,7 +179,8 @@ this release are listed next. form `--KIND`. The new suffix is `__KIND`. For details, see [Disabling links]. - **Heading self-link** support has been reimplemented and projects must now - explicitly enable the feature. For details, see [Heading self links]. + explicitly enable the feature. For details, see [Heading self + links][0.9.0:hsl]. **Footer changes**: refactoring, for easier customization, and simplification. For details concerning all footer changes, see [#1818]. @@ -92,7 +208,7 @@ For details concerning all footer changes, see [#1818]. [Footer layout]: https://www.docsy.dev/blog/2024/0.9.0/#footer-layout [Footer copyright]: https://www.docsy.dev/blog/2024/0.9.0/#footer-copyright [Footer streamlined]: https://www.docsy.dev/blog/2024/0.9.0/#footer-streamlined -[Heading self links]: https://www.docsy.dev/blog/2024/0.9.0/#heading-self-links +[0.9.0:hsl]: https://www.docsy.dev/blog/2024/0.9.0/#heading-self-links [look and feel]: https://www.docsy.dev/blog/2024/0.9.0/#look-and-feel [mermaid]: https://www.docsy.dev/docs/adding-content/diagrams-and-formulae/#diagrams-with-mermaid @@ -109,10 +225,11 @@ For the full list of changes, see the [0.8.0] release notes. **Breaking changes**: -- Docsy is packaged as a **single Hugo module** ([#1120]). - - For details, see [Use Docsy as a Hugo Module]. -- **Important**: non-Hugo-module projects should read the [Docsy NPM install - side-effect] note. +- Docsy is packaged as a **single Hugo module** ([#1120]). For details, see [Use + Docsy as a Hugo Module]. +- **Important**: non-Hugo-module projects should be aware of the [Docsy NPM + install side-effect]. Also, for guidance on Hugo-reported "failed to load + modules" error, see [Docsy as an NPM package]. - **Page feedback**, or [User feedback]: - In support of projects configuring analytics outside of Docsy, feedback functionality is enabled regardless of whether @@ -131,6 +248,8 @@ For the full list of changes, see the [0.8.0] release notes. [#1726]: https://github.com/google/docsy/pull/1726 [#1727]: https://github.com/google/docsy/pull/1727 [0.8.0]: https://github.com/google/docsy/releases/v0.8.0 +[Docsy as an NPM package]: + https://docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package [Docsy NPM install side-effect]: https://docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect [Use Docsy as a Hugo Module]: @@ -206,7 +325,8 @@ For the full list of changes, see the [0.7.0] release notes. - **Shortcodes**: - Now using Hugo's native support for processing HTML & markdown, not file extension testing. ([#906]) - - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939]) + - Dropped support for pre-Hugo-0.54.x behavior of [shortcodes with markdown], + `{{%/*...*/%}}`. ([#939]) - `blocks/section`: **default** and accepted values of the `type` argument have changed! For details, see [blocks/section] ([#1472]). - **Card shortcodes** ([#1376])]: @@ -219,6 +339,8 @@ For the full list of changes, see the [0.7.0] release notes. [chroma-docsy]: https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-chroma +[shortcodes with markdown]: + https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown - **Detection of draw.io diagrams** is now **disabled** by default [#1185] @@ -419,9 +541,10 @@ For the full list of changes, see the [0.2.0] release notes. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1177c58f41..5c62f72695 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,10 +51,10 @@ repo. the end of the file. (Note that change details are autogenerated by GitHub in a later step.) 3. **Update Docsy version** to v0.X.Y for: - - `version` key in [package.json](package.json) - - `version` key in [userguide/hugo.yaml][] -4. Run `npm install` to have vendor assets and [go.mod](go.mod) updated for - dependencies. + - `version` key in [package.json] + - `version` key in [userguide/hugo.yaml] +4. Run `npm run ci:prepare` to ensure that vendor assets and [go.mod] + dependencies are up-to-date. 5. **Submit a PR with your changes**, using a title like "Release v0.X.Y preparation". 6. **Test the PR** branch from selected sites, and push any required @@ -117,19 +117,22 @@ Assuming that Docsy release v0.X.Y has been successfully deployed and use by at least one downstream project, then perform the following actions before any further changes are merged into the default branch: -1. Set `version` in [package.json](package.json) to the next planned (or the - next dot) release with a dev suffix, such as `v0.X.Z-dev.0-unreleased`. +1. Set `version` in [package.json] to the next planned (or the next dot) release + with a dev suffix, such as `v0.X.Z-dev-unreleased`. 2. In the [CHANGELOG]: - **Create a new entry** for the next release by copying the ENTRY TEMPLATE at the end of the file. - **Pin the 0.X.Y release URL**, which ends with `latest?FIXME=...`, to the v0.X.Y release at `https://github.com/google/docsy/releases/v0.x.y`. 3. **Submit a PR with your changes**, using a title like "Set NPM package - version to next unreleased dev vers". + version to next unreleased dev version". 4. **Get PR approved and merged**. -[CHANGELOG]: CHANGELOG.md +[CHANGELOG]: https://github.com/google/docsy/blob/main/CHANGELOG.md [contribution guidelines]: https://www.docsy.dev/docs/contribution-guidelines/ [docsy-example]: https://github.com/google/docsy-example [Draft a new release]: https://github.com/google/docsy/releases/new -[userguide/hugo.yaml]: userguide/hugo.yaml +[go.mod]: https://github.com/google/docsy/blob/main/go.mod +[package.json]: https://github.com/google/docsy/blob/main/package.json +[userguide/hugo.yaml]: + https://github.com/google/docsy/blob/main/userguide/hugo.yaml diff --git a/README.md b/README.md index a68147e22d..34baee170c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,7 @@ # Docsy -[![Project status: active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -[![Project releases](https://img.shields.io/github/release/google/docsy)](https://github.com/google/docsy/releases) -[![Project build Status](https://badges.netlify.com/api/docsydocs.svg?branch=main)](https://app.netlify.com/sites/docsydocs/deploys) -[![Project contributors](https://img.shields.io/github/contributors/google/docsy)](https://github.com/google/docsy/graphs/contributors) -[![Project license](https://img.shields.io/github/license/google/docsy)](https://github.com/google/docsy/blob/main/LICENSE) - -## 🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use official Docsy [releases]. +> **🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use +> official Docsy [releases].** Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets, providing simple navigation, site structure, and more. @@ -95,8 +90,8 @@ requests, see [CONTRIBUTING.md]. Thank you to all past, present, and future ## License -This project is licensed under the Apache License 2.0 - see the -[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for details +This project is licensed under the Apache License 2.0 - see +[LICENSE](https://github.com/google/docsy/blob/main/LICENSE) for details [code of conduct]: https://github.com/google/.github/blob/master/CODE_OF_CONDUCT.md diff --git a/assets/scss/_boxes.scss b/assets/scss/_boxes.scss index c33316099f..6c27d4394f 100644 --- a/assets/scss/_boxes.scss +++ b/assets/scss/_boxes.scss @@ -116,3 +116,21 @@ @each $color, $value in $grays { @include box-variant(".td-box", $color, $value); } + +// Single dark-mode compatibility override for white boxes: +@include color-mode(dark) { + .td-box--white { + color: var(--bs-body-color); + background-color: var(--bs-body-bg); + p > a, span > a { + color: var(--bs-link-color); + &:focus, + &:hover { + color: rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1)); + } + } + .td-arrow-down::before { + border-color: var(--bs-body-bg) transparent transparent transparent; + } + } +} diff --git a/assets/scss/_breadcrumb.scss b/assets/scss/_breadcrumb.scss index 0d32ab7554..387026f70f 100644 --- a/assets/scss/_breadcrumb.scss +++ b/assets/scss/_breadcrumb.scss @@ -2,7 +2,11 @@ .td-breadcrumbs { @media print { - display: none !important; + display: none; + } + + &__single { + display: none; } .breadcrumb { diff --git a/assets/scss/_code.scss b/assets/scss/_code.scss index f6d6747077..43a2fc70d6 100644 --- a/assets/scss/_code.scss +++ b/assets/scss/_code.scss @@ -25,7 +25,7 @@ button.td-click-to-copy { position: absolute; - color: $gray-400; + color: var(--bs-tertiary-color); border-width: 0; background-color: transparent; background-image: none; @@ -35,12 +35,12 @@ top: 2px; &:hover { - color: $dark; - background-color: $gray-400; + color: var(--bs-secondary-color); + background-color: var(--bs-dark-bg-subtle); } &:active { - color: $dark; - background-color: $gray-400; + color: var(--bs-secondary-color); + background-color: var(--bs-dark-bg-subtle); transform: translateY(2px); } } diff --git a/assets/scss/_content.scss b/assets/scss/_content.scss index 364aff2421..165aab8a08 100644 --- a/assets/scss/_content.scss +++ b/assets/scss/_content.scss @@ -47,8 +47,8 @@ blockquote { padding: 0 0 0 1rem; margin-bottom: $spacer; - color: $gray-600; - border-left: 6px solid $secondary; + color: var(--bs-secondary-color); + border-left: 6px solid var(--bs-primary); } ul li, @@ -96,7 +96,7 @@ } .td-heading-self-link { - &:before { + &::before { content: '#'; } diff --git a/assets/scss/_drawio.scss b/assets/scss/_drawio.scss index 0bbafe6342..6dd735e269 100644 --- a/assets/scss/_drawio.scss +++ b/assets/scss/_drawio.scss @@ -23,7 +23,7 @@ div.drawioframe { height: 100%; width: 100%; top: 0; - left: 0px; + left: 0; z-index: 1000; background: #000b; border: 0; diff --git a/assets/scss/_nav.scss b/assets/scss/_nav.scss index dde0e276ce..8087f906e4 100644 --- a/assets/scss/_nav.scss +++ b/assets/scss/_nav.scss @@ -114,7 +114,7 @@ li i { padding-right: 0.5em; - &:before { + &::before { display: inline-block; text-align: center; min-width: 1em; @@ -127,7 +127,7 @@ border: 0; font-weight: inherit; - &:before { + &::before { display: inline-block; font-style: normal; font-variant: normal; @@ -182,7 +182,7 @@ nav.foldable-nav { padding-left: 1.5em; } - .ul-1 .with-child > label:before { + .ul-1 .with-child > label::before { display: inline-block; font-style: normal; font-variant: normal; @@ -196,15 +196,15 @@ nav.foldable-nav { padding-left: 0.4em; padding-right: 0.4em; font-size: 1em; - color: $gray-900; + color: var(--bs-secondary-color); transition: all 0.5s; &:hover { transform: rotate(90deg); } } - .ul-1 .with-child > input:checked ~ label:before { - color: $primary; + .ul-1 .with-child > input:checked ~ label::before { + color: var(--bs-secondary-color); transform: rotate(90deg); transition: transform 0.5s; } @@ -216,13 +216,13 @@ nav.foldable-nav { @media (hover: hover) and (pointer: fine) { nav.foldable-nav { - .ul-1 .with-child > label:hover:before { - color: $primary; + .ul-1 .with-child > label:hover::before { + color: var(--bs-link-color); transition: color 0.3s; } - .ul-1 .with-child > input:checked ~ label:hover:before { - color: $primary; + .ul-1 .with-child > input:checked ~ label:hover::before { + color: var(--bs-link-color); transition: color 0.3s; } } diff --git a/assets/scss/_search.scss b/assets/scss/_search.scss index ad97201966..3df37e55ad 100644 --- a/assets/scss/_search.scss +++ b/assets/scss/_search.scss @@ -19,7 +19,7 @@ // Click-through to the underlying input. pointer-events: none; - &:before { + &::before { @extend .fa; content: fa-content($fa-var-search); } @@ -67,7 +67,7 @@ } .td-search-input { - text-indent: 0px; + text-indent: 0; } } @@ -114,7 +114,7 @@ // cursor: pointer; float: right; - &:after { + &::after { @extend .fas; content: fa-content($fa-var-times); } diff --git a/assets/scss/_sidebar-toc.scss b/assets/scss/_sidebar-toc.scss index dd7def1ec5..1b13966010 100644 --- a/assets/scss/_sidebar-toc.scss +++ b/assets/scss/_sidebar-toc.scss @@ -4,7 +4,7 @@ .td-sidebar-toc { @include link-decoration; - border-left: 1px solid $border-color; + border-left: 1px solid var(--bs-border-color); @supports (position: sticky) { position: sticky; diff --git a/assets/scss/_sidebar-tree.scss b/assets/scss/_sidebar-tree.scss index 6c1825aa0c..07eb74185b 100644 --- a/assets/scss/_sidebar-tree.scss +++ b/assets/scss/_sidebar-tree.scss @@ -39,7 +39,8 @@ list-style: none; } - &.ul-0, ul { + &.ul-0, + ul { padding: 0; margin: 0; } @@ -62,7 +63,7 @@ } a { - color: var(--bs-emphasis-color); + color: var(--bs-secondary-color); } } @@ -79,7 +80,7 @@ a { &:focus, &:hover { - color: $link-color; + color: var(--bs-link-color); } &.active { @@ -87,14 +88,9 @@ } } - .dropdown { - a { - color: $gray-700; - } - - .nav-link { - padding: 0 0 1rem; - } + .dropdown .nav-link { + padding-left: 1.5rem; + margin-bottom: 0.5rem; } & > .td-sidebar-nav__section { @@ -104,7 +100,7 @@ li i { // Layout of icons padding-right: 0.5em; - &:before { + &::before { display: inline-block; text-align: center; min-width: 1em; @@ -113,8 +109,7 @@ .td-sidebar-link.tree-root { font-weight: $font-weight-bold; - color: $td-sidebar-tree-root-color; - border-bottom: 1px $td-sidebar-tree-root-color solid; + border-bottom: 1px solid var(--bs-tertiary-color); margin-bottom: 1rem; } } @@ -124,16 +119,15 @@ @include media-breakpoint-up(md) { padding-top: 4rem; - background-color: $td-sidebar-bg-color; padding-right: 1rem; - border-right: 1px solid $td-sidebar-border-color; + border-right: 1px solid var(--bs-border-color); } padding-bottom: 1rem; &__toggle { line-height: 1; - color: var(--bs-emphasis-color); + color: var(--bs-body-color); margin: 1rem; } diff --git a/assets/scss/_taxonomy.scss b/assets/scss/_taxonomy.scss index c1ff998f9a..2af00fe202 100644 --- a/assets/scss/_taxonomy.scss +++ b/assets/scss/_taxonomy.scss @@ -24,9 +24,9 @@ display: inline-block; width: 100%; font-size: 1rem; - font-weight: 700; - color: $primary; - border-bottom: 1px $primary solid; + font-weight: $font-weight-bold; + color: var(--bs-primary-text-emphasis); + border-bottom: 1px solid var(--bs-tertiary-color); margin-bottom: 1em; padding-bottom: 0.375rem; margin-top: 1em; @@ -105,14 +105,14 @@ margin-left: 0.6em; text-align: center; border-radius: 1em; - background-color: $white; + background-color: var(--bs-body-bg); } .taxonomy-term { - background: $gray-200; + background: var(--bs-secondary-bg); border-width: 0; border-radius: 0 3px 3px 0; - color: $gray-600; + color: var(--bs-body-color); display: inline-block; font-size: 1em; line-height: 1.5em; @@ -127,11 +127,11 @@ clip-path: polygon(100% 0, 100% 100%, 0.8em 100%, 0 50%, 0.8em 0); &:hover { - background-color: $primary; - color: $white; + background-color: var(--bs-primary-bg-subtle); + color: var(--bs-body-color-dark); .taxonomy-count { - color: $dark !important; + color: var(--bs-body-color-dark); } } @@ -288,7 +288,7 @@ margin-bottom: 1.5rem; } -.article-teaser.article-type-docs h3 a:before { +.article-teaser.article-type-docs h3 a::before { display: inline-block; font-style: normal; font-variant: normal; @@ -299,7 +299,7 @@ padding-right: 0.5em; } -.article-teaser.article-type-blog h3 a:before { +.article-teaser.article-type-blog h3 a::before { display: inline-block; font-style: normal; font-variant: normal; @@ -315,7 +315,7 @@ line-height: 1.2; font-size: 1.5rem; - &:before { + &::before { display: inline-block; font-style: normal; font-variant: normal; @@ -334,11 +334,11 @@ } .breadcrumb { - margin-bottom: 0em; + margin-bottom: 0; font-size: 0.85rem; } .article-meta { - margin-bottom: 0em; + margin-bottom: 0; } } diff --git a/assets/scss/_tocbot.scss b/assets/scss/_tocbot.scss new file mode 100644 index 0000000000..4e58a92b3e --- /dev/null +++ b/assets/scss/_tocbot.scss @@ -0,0 +1,4 @@ +// Override active link color +.is-active-link::before { + background-color: $primary !important; +} \ No newline at end of file diff --git a/assets/scss/_variables.scss b/assets/scss/_variables.scss index 8fda832333..434d40ff2f 100644 --- a/assets/scss/_variables.scss +++ b/assets/scss/_variables.scss @@ -26,11 +26,6 @@ $code-color: shade-color($secondary, 40%) !default; // UI element colors -$border-color: $gray-300 !default; -$td-sidebar-tree-root-color: $primary !default; -$td-sidebar-bg-color: rgba($primary, 0.03) !default; -$td-sidebar-border-color: $border-color !default; - // Background colors for the sections on home page etc. It is a paint by number // system, starting at 0, where the number is taken from the shortcode's ordinal // if not provided by the user. These colors are all part of the theme palette, diff --git a/assets/scss/main.scss b/assets/scss/main.scss index 710c943991..51af0beffb 100644 --- a/assets/scss/main.scss +++ b/assets/scss/main.scss @@ -8,9 +8,9 @@ @import "../vendor/bootstrap/scss/bootstrap"; @import "support/bootstrap_vers_test"; -@import "../vendor/Font-Awesome/scss/fontawesome.scss"; -@import "../vendor/Font-Awesome/scss/solid.scss"; -@import "../vendor/Font-Awesome/scss/brands.scss"; +@import "../vendor/Font-Awesome/scss/fontawesome"; +@import "../vendor/Font-Awesome/scss/solid"; +@import "../vendor/Font-Awesome/scss/brands"; @import "variables_project_after_bs"; @@ -34,8 +34,10 @@ @import "taxonomy"; @import "drawio"; @import "shortcodes"; +@import "tocbot"; @import "swagger"; - +@import "support/rtl"; +@import "tocbot"; @if $td-enable-google-fonts { @import url($web-font-path); @@ -101,10 +103,10 @@ visibility: hidden; } - h2[id]:before, - h3[id]:before, - h4[id]:before, - h5[id]:before { + h2[id]::before, + h3[id]::before, + h4[id]::before, + h5[id]::before { display: block; content: " "; margin-top: -5rem; diff --git a/assets/scss/rtl/_main.scss b/assets/scss/rtl/_main.scss deleted file mode 100644 index 6ea131e314..0000000000 --- a/assets/scss/rtl/_main.scss +++ /dev/null @@ -1,55 +0,0 @@ -body:lang(fa), -body:lang(ar), -body:lang(az), -body:lang(dv), -body:lang(he), -body:lang(ku), -body:lang(ur) { - @import "spacing"; - - direction: rtl; - text-align: right; - - .dropdown-menu { - text-align: right; - } - - .text-right { - text-align: left !important; - } - - pre { - text-align: left; - direction: ltr; - } - - .td-rss-button { - left: 1rem !important; - right: auto !important; - } -} - -body:lang(fa) { - @import url("https://cdn.jsdelivr.net/gh/rastikerdar/vazir-font@v27.0.1/dist/font-face.css"); - font-family: "Vazir", "Open Sans", -apple-system, BlinkMacSystemFont, - "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", - "Segoe UI Emoji", "Segoe UI Symbol"; -} - -body:lang(he) { - @if $td-enable-google-fonts { - @import url("https://fonts.googleapis.com/css2?family=Rubik:wght@300;400;500;600;700&display=swap"); - } - font-family: "Rubik", "Open Sans", -apple-system, BlinkMacSystemFont, - "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", - "Segoe UI Emoji", "Segoe UI Symbol"; -} - -body:lang(ar) { - @if $td-enable-google-fonts { - @import url("https://fonts.googleapis.com/css2?family=Tajawal:wght@300;400;500;700&display=swap"); - } - font-family: "Tajawal", "Open Sans", -apple-system, BlinkMacSystemFont, - "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", - "Segoe UI Emoji", "Segoe UI Symbol"; -} diff --git a/assets/scss/rtl/_spacing.scss b/assets/scss/rtl/_spacing.scss deleted file mode 100644 index 6ead6b0dd9..0000000000 --- a/assets/scss/rtl/_spacing.scss +++ /dev/null @@ -1,87 +0,0 @@ -@each $breakpoint in map-keys($grid-breakpoints) { - @include media-breakpoint-up($breakpoint) { - $infix: breakpoint-infix($breakpoint, $grid-breakpoints); - - @each $prop, $abbrev in (margin: m, padding: p) { - @each $size, $length in $spacers { - .#{$abbrev}#{$infix}-#{$size} { - #{$prop}: $length !important; - } - - .#{$abbrev}t#{$infix}-#{$size}, - .#{$abbrev}y#{$infix}-#{$size} { - #{$prop}-top: $length !important; - } - - .#{$abbrev}r#{$infix}-#{$size}, - .#{$abbrev}x#{$infix}-#{$size} { - #{$prop}-inline-end: $length !important; - } - - .#{$abbrev}b#{$infix}-#{$size}, - .#{$abbrev}y#{$infix}-#{$size} { - #{$prop}-bottom: $length !important; - } - - .#{$abbrev}l#{$infix}-#{$size}, - .#{$abbrev}x#{$infix}-#{$size} { - #{$prop}-inline-start: $length !important; - } - } - } - - // Negative margins (e.g., where `.mb-n1` is negative version of `.mb-1`) - @each $size, $length in $spacers { - @if $size !=0 { - .m#{$infix}-n#{$size} { - margin: -$length !important; - } - - .mt#{$infix}-n#{$size}, - .my#{$infix}-n#{$size} { - margin-top: -$length !important; - } - - .mr#{$infix}-n#{$size}, - .mx#{$infix}-n#{$size} { - margin-right: -$length !important; - } - - .mb#{$infix}-n#{$size}, - .my#{$infix}-n#{$size} { - margin-bottom: -$length !important; - } - - .ml#{$infix}-n#{$size}, - .mx#{$infix}-n#{$size} { - margin-left: -$length !important; - } - } - } - - // Some special margin utils - .m#{$infix}-auto { - margin: auto !important; - } - - .mt#{$infix}-auto, - .my#{$infix}-auto { - margin-top: auto !important; - } - - .mr#{$infix}-auto, - .mx#{$infix}-auto { - margin-right: auto !important; - } - - .mb#{$infix}-auto, - .my#{$infix}-auto { - margin-bottom: auto !important; - } - - .ml#{$infix}-auto, - .mx#{$infix}-auto { - margin-left: auto !important; - } - } -} diff --git a/assets/scss/section-index.scss b/assets/scss/section-index.scss index c34d699768..bda9a11209 100644 --- a/assets/scss/section-index.scss +++ b/assets/scss/section-index.scss @@ -7,7 +7,7 @@ margin-bottom: 0; a { - font-weight: 700; + font-weight: $font-weight-bold; } } diff --git a/assets/scss/shortcodes.scss b/assets/scss/shortcodes.scss index 517d3e8225..eb05199821 100644 --- a/assets/scss/shortcodes.scss +++ b/assets/scss/shortcodes.scss @@ -1,2 +1,2 @@ -@import "shortcodes/tabbed-pane.scss"; -@import "shortcodes/cards-pane.scss"; +@import "shortcodes/tabbed-pane"; +@import "shortcodes/cards-pane"; diff --git a/assets/scss/shortcodes/tabbed-pane.scss b/assets/scss/shortcodes/tabbed-pane.scss index 680a965539..7d8647e833 100644 --- a/assets/scss/shortcodes/tabbed-pane.scss +++ b/assets/scss/shortcodes/tabbed-pane.scss @@ -10,7 +10,7 @@ border: none; max-width: 100%; } - margin-top: 0rem; + margin-top: 0; margin-bottom: 1.5rem; border-left: $nav-tabs-border-width solid $nav-tabs-border-color; border-right: $nav-tabs-border-width solid $nav-tabs-border-color; diff --git a/layouts/partials/hooks/body-end.html b/assets/scss/support/_rtl.scss similarity index 100% rename from layouts/partials/hooks/body-end.html rename to assets/scss/support/_rtl.scss diff --git a/assets/scss/support/_utilities.scss b/assets/scss/support/_utilities.scss index c691c3b355..245c2bb9d5 100644 --- a/assets/scss/support/_utilities.scss +++ b/assets/scss/support/_utilities.scss @@ -25,10 +25,7 @@ &::after { content: ""; position: absolute; - top: 0; - right: 0; - bottom: 0; - left: 0; + inset: 0; } &--dark::after { diff --git a/assets/scss/td/_code-dark.scss b/assets/scss/td/_code-dark.scss new file mode 100644 index 0000000000..e411099bad --- /dev/null +++ b/assets/scss/td/_code-dark.scss @@ -0,0 +1,10 @@ +[data-bs-theme="light"] { + @import 'td/chroma/light'; +} + +[data-bs-theme="dark"] { + @import 'td/chroma/dark'; + .chroma { + background-color: var(--td-pre-bg); + } +} diff --git a/assets/scss/td/chroma/_dark.scss b/assets/scss/td/chroma/_dark.scss new file mode 100644 index 0000000000..5e34333e04 --- /dev/null +++ b/assets/scss/td/chroma/_dark.scss @@ -0,0 +1,89 @@ +/* Chroma style: onedark */ +/* Generated using: hugo gen chromastyles --style=onedark */ + +/* Background */ .bg { color:#abb2bf;background-color:#282c34; } +/* PreWrapper */ .chroma { color:#abb2bf;background-color:#282c34; } +/* Other */ .chroma .x { } +/* Error */ .chroma .err { } +/* CodeLine */ .chroma .cl { } +/* LineLink */ .chroma .lnlinks { outline:none;text-decoration:none;color:inherit } +/* LineTableTD */ .chroma .lntd { vertical-align:top;padding:0;margin:0;border:0; } +/* LineTable */ .chroma .lntable { border-spacing:0;padding:0;margin:0;border:0; } +/* LineHighlight */ .chroma .hl { background-color:#3d4148 } +/* LineNumbersTable */ .chroma .lnt { white-space:pre;-webkit-user-select:none;user-select:none;margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#55595f } +/* LineNumbers */ .chroma .ln { white-space:pre;-webkit-user-select:none;user-select:none;margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#55595f } +/* Line */ .chroma .line { display:flex; } +/* Keyword */ .chroma .k { color:#c678dd } +/* KeywordConstant */ .chroma .kc { color:#e5c07b } +/* KeywordDeclaration */ .chroma .kd { color:#c678dd } +/* KeywordNamespace */ .chroma .kn { color:#c678dd } +/* KeywordPseudo */ .chroma .kp { color:#c678dd } +/* KeywordReserved */ .chroma .kr { color:#c678dd } +/* KeywordType */ .chroma .kt { color:#e5c07b } +/* Name */ .chroma .n { color:#e06c75 } +/* NameAttribute */ .chroma .na { color:#e06c75 } +/* NameClass */ .chroma .nc { color:#e5c07b } +/* NameConstant */ .chroma .no { color:#e06c75 } +/* NameDecorator */ .chroma .nd { color:#61afef } +/* NameEntity */ .chroma .ni { color:#e06c75 } +/* NameException */ .chroma .ne { color:#e06c75 } +/* NameLabel */ .chroma .nl { color:#e06c75 } +/* NameNamespace */ .chroma .nn { color:#e06c75 } +/* NameOther */ .chroma .nx { color:#e06c75 } +/* NameProperty */ .chroma .py { color:#e06c75 } +/* NameTag */ .chroma .nt { color:#e06c75 } +/* NameBuiltin */ .chroma .nb { color:#e5c07b } +/* NameBuiltinPseudo */ .chroma .bp { color:#e5c07b } +/* NameVariable */ .chroma .nv { color:#e06c75 } +/* NameVariableClass */ .chroma .vc { color:#e06c75 } +/* NameVariableGlobal */ .chroma .vg { color:#e06c75 } +/* NameVariableInstance */ .chroma .vi { color:#e06c75 } +/* NameVariableMagic */ .chroma .vm { color:#e06c75 } +/* NameFunction */ .chroma .nf { color:#61afef;font-weight:bold } +/* NameFunctionMagic */ .chroma .fm { color:#56b6c2;font-weight:bold } +/* Literal */ .chroma .l { } +/* LiteralDate */ .chroma .ld { } +/* LiteralString */ .chroma .s { color:#98c379 } +/* LiteralStringAffix */ .chroma .sa { color:#98c379 } +/* LiteralStringBacktick */ .chroma .sb { color:#98c379 } +/* LiteralStringChar */ .chroma .sc { color:#98c379 } +/* LiteralStringDelimiter */ .chroma .dl { color:#98c379 } +/* LiteralStringDoc */ .chroma .sd { color:#98c379 } +/* LiteralStringDouble */ .chroma .s2 { color:#98c379 } +/* LiteralStringEscape */ .chroma .se { color:#98c379 } +/* LiteralStringHeredoc */ .chroma .sh { color:#98c379 } +/* LiteralStringInterpol */ .chroma .si { color:#98c379 } +/* LiteralStringOther */ .chroma .sx { color:#98c379 } +/* LiteralStringRegex */ .chroma .sr { color:#98c379 } +/* LiteralStringSingle */ .chroma .s1 { color:#98c379 } +/* LiteralStringSymbol */ .chroma .ss { color:#98c379 } +/* LiteralNumber */ .chroma .m { color:#d19a66 } +/* LiteralNumberBin */ .chroma .mb { color:#d19a66 } +/* LiteralNumberFloat */ .chroma .mf { color:#d19a66 } +/* LiteralNumberHex */ .chroma .mh { color:#d19a66 } +/* LiteralNumberInteger */ .chroma .mi { color:#d19a66 } +/* LiteralNumberIntegerLong */ .chroma .il { color:#d19a66 } +/* LiteralNumberOct */ .chroma .mo { color:#d19a66 } +/* Operator */ .chroma .o { color:#56b6c2 } +/* OperatorWord */ .chroma .ow { color:#56b6c2 } +/* Punctuation */ .chroma .p { } +/* Comment */ .chroma .c { color:#7f848e } +/* CommentHashbang */ .chroma .ch { color:#7f848e } +/* CommentMultiline */ .chroma .cm { color:#7f848e } +/* CommentSingle */ .chroma .c1 { color:#7f848e } +/* CommentSpecial */ .chroma .cs { color:#7f848e } +/* CommentPreproc */ .chroma .cp { color:#7f848e } +/* CommentPreprocFile */ .chroma .cpf { color:#7f848e } +/* Generic */ .chroma .g { } +/* GenericDeleted */ .chroma .gd { color:#e06c75 } +/* GenericEmph */ .chroma .ge { } +/* GenericError */ .chroma .gr { } +/* GenericHeading */ .chroma .gh { } +/* GenericInserted */ .chroma .gi { color:#98c379;font-weight:bold } +/* GenericOutput */ .chroma .go { } +/* GenericPrompt */ .chroma .gp { } +/* GenericStrong */ .chroma .gs { } +/* GenericSubheading */ .chroma .gu { } +/* GenericTraceback */ .chroma .gt { } +/* GenericUnderline */ .chroma .gl { } +/* TextWhitespace */ .chroma .w { } diff --git a/assets/scss/td/chroma/_light.scss b/assets/scss/td/chroma/_light.scss new file mode 100644 index 0000000000..45e1a454f9 --- /dev/null +++ b/assets/scss/td/chroma/_light.scss @@ -0,0 +1,89 @@ +/* Chroma style: tango */ +/* Generated using: hugo gen chromastyles --style=tango */ + +/* Background */ .bg { background-color:#f8f8f8; } +/* PreWrapper */ .chroma { background-color:#f8f8f8; } +/* Other */ .chroma .x { color:#000 } +/* Error */ .chroma .err { color:#a40000 } +/* CodeLine */ .chroma .cl { } +/* LineLink */ .chroma .lnlinks { outline:none;text-decoration:none;color:inherit } +/* LineTableTD */ .chroma .lntd { vertical-align:top;padding:0;margin:0;border:0; } +/* LineTable */ .chroma .lntable { border-spacing:0;padding:0;margin:0;border:0; } +/* LineHighlight */ .chroma .hl { background-color:#dfdfdf } +/* LineNumbersTable */ .chroma .lnt { white-space:pre;-webkit-user-select:none;user-select:none;margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#7f7f7f } +/* LineNumbers */ .chroma .ln { white-space:pre;-webkit-user-select:none;user-select:none;margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#7f7f7f } +/* Line */ .chroma .line { display:flex; } +/* Keyword */ .chroma .k { color:#204a87;font-weight:bold } +/* KeywordConstant */ .chroma .kc { color:#204a87;font-weight:bold } +/* KeywordDeclaration */ .chroma .kd { color:#204a87;font-weight:bold } +/* KeywordNamespace */ .chroma .kn { color:#204a87;font-weight:bold } +/* KeywordPseudo */ .chroma .kp { color:#204a87;font-weight:bold } +/* KeywordReserved */ .chroma .kr { color:#204a87;font-weight:bold } +/* KeywordType */ .chroma .kt { color:#204a87;font-weight:bold } +/* Name */ .chroma .n { color:#000 } +/* NameAttribute */ .chroma .na { color:#c4a000 } +/* NameClass */ .chroma .nc { color:#000 } +/* NameConstant */ .chroma .no { color:#000 } +/* NameDecorator */ .chroma .nd { color:#5c35cc;font-weight:bold } +/* NameEntity */ .chroma .ni { color:#ce5c00 } +/* NameException */ .chroma .ne { color:#c00;font-weight:bold } +/* NameLabel */ .chroma .nl { color:#f57900 } +/* NameNamespace */ .chroma .nn { color:#000 } +/* NameOther */ .chroma .nx { color:#000 } +/* NameProperty */ .chroma .py { color:#000 } +/* NameTag */ .chroma .nt { color:#204a87;font-weight:bold } +/* NameBuiltin */ .chroma .nb { color:#204a87 } +/* NameBuiltinPseudo */ .chroma .bp { color:#3465a4 } +/* NameVariable */ .chroma .nv { color:#000 } +/* NameVariableClass */ .chroma .vc { color:#000 } +/* NameVariableGlobal */ .chroma .vg { color:#000 } +/* NameVariableInstance */ .chroma .vi { color:#000 } +/* NameVariableMagic */ .chroma .vm { color:#000 } +/* NameFunction */ .chroma .nf { color:#000 } +/* NameFunctionMagic */ .chroma .fm { color:#000 } +/* Literal */ .chroma .l { color:#000 } +/* LiteralDate */ .chroma .ld { color:#000 } +/* LiteralString */ .chroma .s { color:#4e9a06 } +/* LiteralStringAffix */ .chroma .sa { color:#4e9a06 } +/* LiteralStringBacktick */ .chroma .sb { color:#4e9a06 } +/* LiteralStringChar */ .chroma .sc { color:#4e9a06 } +/* LiteralStringDelimiter */ .chroma .dl { color:#4e9a06 } +/* LiteralStringDoc */ .chroma .sd { color:#8f5902;font-style:italic } +/* LiteralStringDouble */ .chroma .s2 { color:#4e9a06 } +/* LiteralStringEscape */ .chroma .se { color:#4e9a06 } +/* LiteralStringHeredoc */ .chroma .sh { color:#4e9a06 } +/* LiteralStringInterpol */ .chroma .si { color:#4e9a06 } +/* LiteralStringOther */ .chroma .sx { color:#4e9a06 } +/* LiteralStringRegex */ .chroma .sr { color:#4e9a06 } +/* LiteralStringSingle */ .chroma .s1 { color:#4e9a06 } +/* LiteralStringSymbol */ .chroma .ss { color:#4e9a06 } +/* LiteralNumber */ .chroma .m { color:#0000cf;font-weight:bold } +/* LiteralNumberBin */ .chroma .mb { color:#0000cf;font-weight:bold } +/* LiteralNumberFloat */ .chroma .mf { color:#0000cf;font-weight:bold } +/* LiteralNumberHex */ .chroma .mh { color:#0000cf;font-weight:bold } +/* LiteralNumberInteger */ .chroma .mi { color:#0000cf;font-weight:bold } +/* LiteralNumberIntegerLong */ .chroma .il { color:#0000cf;font-weight:bold } +/* LiteralNumberOct */ .chroma .mo { color:#0000cf;font-weight:bold } +/* Operator */ .chroma .o { color:#ce5c00;font-weight:bold } +/* OperatorWord */ .chroma .ow { color:#204a87;font-weight:bold } +/* Punctuation */ .chroma .p { color:#000;font-weight:bold } +/* Comment */ .chroma .c { color:#8f5902;font-style:italic } +/* CommentHashbang */ .chroma .ch { color:#8f5902;font-style:italic } +/* CommentMultiline */ .chroma .cm { color:#8f5902;font-style:italic } +/* CommentSingle */ .chroma .c1 { color:#8f5902;font-style:italic } +/* CommentSpecial */ .chroma .cs { color:#8f5902;font-style:italic } +/* CommentPreproc */ .chroma .cp { color:#8f5902;font-style:italic } +/* CommentPreprocFile */ .chroma .cpf { color:#8f5902;font-style:italic } +/* Generic */ .chroma .g { color:#000 } +/* GenericDeleted */ .chroma .gd { color:#a40000 } +/* GenericEmph */ .chroma .ge { color:#000;font-style:italic } +/* GenericError */ .chroma .gr { color:#ef2929 } +/* GenericHeading */ .chroma .gh { color:#000080;font-weight:bold } +/* GenericInserted */ .chroma .gi { color:#00a000 } +/* GenericOutput */ .chroma .go { color:#000;font-style:italic } +/* GenericPrompt */ .chroma .gp { color:#8f5902 } +/* GenericStrong */ .chroma .gs { color:#000;font-weight:bold } +/* GenericSubheading */ .chroma .gu { color:#800080;font-weight:bold } +/* GenericTraceback */ .chroma .gt { color:#a40000;font-weight:bold } +/* GenericUnderline */ .chroma .gl { color:#000;text-decoration:underline } +/* TextWhitespace */ .chroma .w { color:#f8f8f8;text-decoration:underline } diff --git a/go.mod b/go.mod index e03bbb426a..17a7b2eade 100644 --- a/go.mod +++ b/go.mod @@ -5,6 +5,6 @@ go 1.12 // AUTO-GENERATED using `npm run get:hugo-modules` require ( - github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7 // indirect - github.com/twbs/bootstrap v5.3.3+incompatible // indirect + github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3 // indirect + github.com/twbs/bootstrap v5.3.6+incompatible // indirect ) diff --git a/go.sum b/go.sum index aa8b4c3d49..fd58ba038d 100644 --- a/go.sum +++ b/go.sum @@ -1,4 +1,4 @@ -github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7 h1:2aWEKCRLqQ9nPyXaz4/IYtRrDr3PzEiX0DUSUr2/EDs= -github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= -github.com/twbs/bootstrap v5.3.3+incompatible h1:goFoqinzdHfkeegpFP7pvhbd0g+A3O2hbU3XCjuNrEQ= -github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= +github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3 h1:/iluJkJiyTAdnqrw3Yi9rH2HNHhrrtCmj8VJe7I6o3w= +github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= +github.com/twbs/bootstrap v5.3.6+incompatible h1:efmXVyq839m5QQ0+JBUdQQ1TrmoBqvQ5kRhUueKsH+4= +github.com/twbs/bootstrap v5.3.6+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= diff --git a/hugo.yaml b/hugo.yaml index 3930bcf3ef..3909f196bf 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -18,7 +18,7 @@ outputFormats: module: hugoVersion: extended: true - min: 0.110.0 + min: 0.146.0 mounts: - source: assets target: assets @@ -44,7 +44,7 @@ module: target: static/webfonts # Mounts for module installations, # needed to work around a known bug in Go’s module management. - - source: assets/_vendor/bootstrap/scss/ + - source: assets/_vendor/bootstrap/scss target: assets/vendor/bootstrap/scss/vendor imports: - path: github.com/twbs/bootstrap diff --git a/i18n/ar.toml b/i18n/ar.toml index 8035bd935c..0fa45dd871 100644 --- a/i18n/ar.toml +++ b/i18n/ar.toml @@ -1,80 +1,89 @@ # UI strings. Buttons and similar. - [ui_pager_prev] -other = "السابق" +other = "السَّابق" [ui_pager_next] -other = "التالي" +other = "التَّالي" [ui_read_more] -other = "إقرأ المزيد" +other = "اِقْرأ اَلمزِيد" [ui_search] -other = "ابحث في هذا الموقع" +other = "اِبْحث فِي هذَا اَلموْقِع" # Used in sentences such as "Posted in News" [ui_in] -other = "في" +other = "فِي" + # Used in sentences such as "All Tags" [ui_all] -other = "كل" +other = "كُلَّ" # Footer text [footer_all_rights_reserved] -other = "كافة الحقوق محفوظة" +other = "كَافَّة اَلحُقوق مَحفُوظة" [footer_privacy_policy] -other = "سياسة الخصوصية" +other = "سِياسة الخصوصيَّة" - -# Post (blog, articles etc.) +# Post (blog , articles etc.) [post_byline_by] other = "الكاتب" [post_created] -other = "منشئة" +other = "مُنْشِئة" [post_last_mod] -other = "اخر تعديل" +other = "آخر تَعدِيل" [post_edit_this] -other = "عدل هذه الصفحة" +other = "عدل هَذِه الصَّفْحة" [post_view_this] -other = "أنظر مصدر الصفحة" +other = "أَنظُر مَصدَر الصَّفْحة" [post_create_child_page] -other = " أنشئ صفحة فرعية" +other = "أُنْشِئ صَفحَة فَرعِية" [post_create_issue] -other = "أنشئ مسألة حول الوثائق" +other = "أُنْشِئ مَسْأَلة حَوْل الوثائق" [post_create_project_issue] -other = "أنشئ مسألة حول المشروع" +other = "أُنْشِئ مَسْأَلة حَوْل المشْروع" [post_posts_in] -other = "منشور في" +other = "مَنشُور فِي" [post_reading_time] -other = "دقيقة للقراءة" +other = "دَقِيقَة لِلْقراءة" [post_less_than_a_minute_read] -other = "أقل من دقيقة" +other = "أقلَّ مِن دَقِيقَة" # Print support [print_printable_section] -other = "هذا العرض يتضمن عدة صفحات للطباعة ضمن هذا القسم." +other = "هذَا العرْض يَتَضمَّن عِدَّة صَفَحات لِلطِّباعة ضِمْن هذَا القسْم." [print_click_to_print] -other = "اضغط هنا للطباعة" +other = "اِضْغط هُنَا لِلطِّباعة" [print_show_regular] -other = "العودة للعرض العادي" +other = "اَلْعَودة لِلْعرْض العاديِّ" [print_entire_section] -other = "اطبع القسم كاملا" +other = "اِطْبع القسْم كاملا" # Community [community_join] -other = "انضم الي مجتمع {{ .Site.Title }}" +other = "اِنْضمَّ إِلى مُجتَمَع {{ .Site.Title }}" [community_introduce] -other = "{{ .Site.Title }} هو مشروع مفتوح المصدر يمكن لأي شخص في المجتمع استخدامه وتحسينه والاستمتاع به. يسعدنا أن تنضم إلينا! إليك بعض الطرق للمشاركة و معرفة ما يحدث." +other = "{{ .Site.Title }} هُو مَشرُوع مَفتُوح المصْدر يُمْكِن لِأيِّ شَخْص فِي المجْتمع اِسْتخْدامه وتحْسينه والاسْتمْتاع بِه. يُسْعدنَا أن تَنضَم إِليْنَا! إِلَيك بَعْض الطُّرق لِلْمشاركة ومتابعة آخر التَّحْديثات." [community_learn] -other = "تعلم وتواصل" +other = "تَعلُّم وتواصل" [community_using] -other = "تستخدام أو تريد استخدام {{ .Site.Title }}؟ اكتشف المزيد هنا:" +other = "تِسْتخْدام أو تُريد اِسْتخْدام {{ .Site.Title }} ؟ اِكتشَف اَلمزِيد هُنَا:" [community_develop] -other = "طور و ساهم" +other = "طَوَّر وساهم " [community_contribute] -other = "إذا كنت ترغب في المشاركة بشكل أكبر من خلال المساهمة في {{ .Site.Title }}, انضم إلينا هنا:" +other = "إِذَا كُنْت تَرغَب فِي المشاركة بِشَكل أَكبَر مِن خِلَال المساهمة فِي {{ .Site.Title }} ،اِنْضمَّ إِليْنَا هُنَا:" [community_how_to] -other = "يمكنك معرفة كيفية المساهمة في {{ .Site.Title }} من خلال" +other = "يُمْكِنك مَعرِفة كَيفِية المساهمة فِي {{ .Site.Title }} مِن خِلَال" [community_guideline] -other = "إرشادات المساهمة" +other = "إِرْشادات المساهمة" + +# Feedback +[feedback_title] +other = "تَقيِيم الأدَاء" +[feedback_question] +other = "هل كَانَت هَذِه الصَّفْحة مُفيدَة" +[feedback_positive] +other = "نعم" +[feedback_negative] +other = "لََا" diff --git a/i18n/fa.toml b/i18n/fa.toml index 70956fce9f..c7cbe76e37 100644 --- a/i18n/fa.toml +++ b/i18n/fa.toml @@ -1,5 +1,3 @@ - - # UI strings. Buttons and similar. [ui_pager_prev] @@ -35,6 +33,8 @@ other = "ساخته شده" other = "آخرین تغییرات" [post_edit_this] other = "این صفحه را ویرایش کنید" +[post_view_this] +other = "مشاهده منبع صفحه" [post_create_child_page] other = "ایجاد زیر صفحه در این صفحه" [post_create_issue] @@ -76,3 +76,13 @@ other = "If you want to get more involved by contributing to {{ .Site.Title }}, other = "You can find out how to contribute to {{ .Site.Title }} in our" [community_guideline] other = "Contribution Guidelines" + +# Feedback +[feedback_title] +other = "بازخورد" +[feedback_question] +other = "این صفحه به شما کمک کرد؟" +[feedback_positive] +other = "آره" +[feedback_negative] +other = "نه" diff --git a/i18n/fr.toml b/i18n/fr.toml index 035f0e9313..b2e6a3c997 100644 --- a/i18n/fr.toml +++ b/i18n/fr.toml @@ -77,3 +77,14 @@ other = "Si vous voulez vous impliquer davantage en contribuant à {{ .Site.Titl other = "Vous pouvez trouver comment contribuer à {{ .Site.Title }} dans nos" [community_guideline] other = "Règles de contribution" + +# Feedback +[feedback_title] +other = "Feedback" +[feedback_question] +other = "Cette page est-elle utile?" +[feedback_positive] +other = "Oui" +[feedback_negative] +other = "Non" + diff --git a/i18n/ja.toml b/i18n/ja.toml index 5c714c9d29..9bf803cbb8 100644 --- a/i18n/ja.toml +++ b/i18n/ja.toml @@ -77,3 +77,13 @@ other = "If you want to get more involved by contributing to {{ .Site.Title }}, other = "You can find out how to contribute to {{ .Site.Title }} in our" [community_guideline] other = "Contribution Guidelines" + +# Feedback +[feedback_title] +other = "フィードバック" +[feedback_question] +other = "このページは役に立ちましたか?" +[feedback_positive] +other = "役に立った" +[feedback_negative] +other = "役に立たなかった" diff --git a/i18n/no.toml b/i18n/no.toml index 19f51445d4..b2b79fe454 100644 --- a/i18n/no.toml +++ b/i18n/no.toml @@ -20,10 +20,10 @@ other = "i" # Footer text [footer_all_rights_reserved] -other = "Alle retter er reservert" +other = "Alle rettigheter er reservert" [footer_privacy_policy] -other = "Privacy Policy" +other = "Personvernpolicy" # Post (blog, articles etc.) @@ -36,42 +36,44 @@ other = "Sist endret" [post_edit_this] other = "Endre denne siden" [post_create_child_page] -other = "Create child page" +other = "Lag underside" [post_create_issue] other = "Opprett dokumentasjon sak" [post_create_project_issue] other = "Opprett prosjekt sak" [post_posts_in] -other = "Poster i" +other = "Poster til" [post_reading_time] other = "minute read" [post_less_than_a_minute_read] other = "less than a minute" +[post_view_this] +other = "Vis kildekoden" # Print support [print_printable_section] -other = "This is the multi-page printable view of this section." +other = "Dette er flersidevisningen av denne seksjonen." [print_click_to_print] -other = "Click here to print" +other = "Klikk her for å skrive ut" [print_show_regular] -other = "Return to the regular view of this page" +other = "Gå tilbake til vanlig sidevisning" [print_entire_section] -other = "Print entire section" +other = "Skriv ut hele seksjonen" # Community [community_join] -other = "Join the {{ .Site.Title }} community" +other = "Bli med i {{ .Site.Title }} fellesskapet" [community_introduce] -other = "{{ .Site.Title }} is an open source project that anyone in the community can use, improve, and enjoy. We'd love you to join us! Here's a few ways to find out what's happening and get involved." +other = "{{ .Site.Title }} er et åpen kildekodeprosjekt som alle kan bruke, forbedre og glede seg over. Bli med - her er noen måter du kan holde deg oppdatert på og bidra." [community_learn] -other = "Learn and Connect" +other = "Lær og få kontakt" [community_using] -other = "Using or want to use {{ .Site.Title }}? Find out more here:" +other = "Bruker du, eller har du lyst til å bruke {{ .Site.Title }}? Lær mer her:" [community_develop] -other = "Develop and Contribute" +other = "Bidra og videreutvikle" [community_contribute] -other = "If you want to get more involved by contributing to {{ .Site.Title }}, join us here:" +other = "Dersom du vil involvere deg mer ved å bidra til {{ .Site.Title }}, bli med oss her:" [community_how_to] -other = "You can find out how to contribute to {{ .Site.Title }} in our" +other = "Du kan finne ut hvordan du bidrar til {{ .Site.Title }} i vår" [community_guideline] -other = "Contribution Guidelines" +other = "Retningslinjer for bidrag" diff --git a/i18n/oc.toml b/i18n/oc.toml new file mode 100644 index 0000000000..7ac7f70b8b --- /dev/null +++ b/i18n/oc.toml @@ -0,0 +1,90 @@ +# UI strings. Buttons and similar. + +[ui_pager_prev] +other = "Precedent" + +[ui_pager_next] +other = "Seguent" + +[ui_read_more] +other = "Ne legir mai" + +[ui_search] +other = "Cercar dins lo site…" + +# Used in sentences such as "Posted in News" +[ui_in] +other = "Dins" + +# Used in sentences such as "All Tags" +[ui_all] +other = "Totas" + +# Footer text +[footer_all_rights_reserved] +other = "Tot drech reservat" + +[footer_privacy_policy] +other = "Politica de confidencialitat" + +# Post (blog, articles etc.) +[post_byline_by] +other = "Per" +[post_created] +other = "Creacion" +[post_last_mod] +other = "Darrièra modificacion" +[post_edit_this] +other = "Modificar aquesta pagina" +[post_view_this] +other = "Veire la pagina font" +[post_create_child_page] +other = "Crear una pagina enfant" +[post_create_issue] +other = "Crear una anomalia de documentacion" +[post_create_project_issue] +other = "Crear una anomalia de projècte" +[post_posts_in] +other = "Publicacions dins" +[post_reading_time] +other = "minutas de lectura" +[post_less_than_a_minute_read] +other = "mens d'una minuta de lectura" + +# Print support +[print_printable_section] +other = "Aquò es una vista multipagina imprimibla de la seccion." +[print_click_to_print] +other = "Clicar aquí per imprimir" +[print_show_regular] +other = "Tornar a la vista normala d'aquesta pagina" +[print_entire_section] +other = "Imprimir la seccion complèta" + +# Community +[community_join] +other = "Rejónher la comunitat {{ .Site.Title }}" +[community_introduce] +other = "{{ .Site.Title }} es un projècte liure que totòm dins la comunitat pòt utilizar, melhorar e n'aprofichar. Nos agradariá que nos rejonguèssetz ! Vaquí d'unas etapas per saber çò que se passa e s'implicar." +[community_learn] +other = "Aprendre e se connectar" +[community_using] +other = "Utilizatz o volètz utilizar {{ .Site.Title }} ? Aprenètz-ne mai aquí :" +[community_develop] +other = "Desvelopar e contribuir" +[community_contribute] +other = "Se volètz vos implicar en contribuissent a {{ .Site.Title }}, retrobatz-nos :" +[community_how_to] +other = "Podètz trobar cossí contribuir a {{ .Site.Title }} dins nòstra" +[community_guideline] +other = "Guida de contribucion" + +# Feedback +[feedback_title] +other = "Feedback" +[feedback_question] +other = "Èra utila aquesta pagina ?" +[feedback_positive] +other = "Oc" +[feedback_negative] +other = "Non" diff --git a/i18n/pt-br.toml b/i18n/pt-br.toml index 282b5f7126..c40800a995 100644 --- a/i18n/pt-br.toml +++ b/i18n/pt-br.toml @@ -1,5 +1,3 @@ - - # UI strings. Buttons and similar. [ui_pager_prev] @@ -18,6 +16,10 @@ other = "Buscar no site…" [ui_in] other = "em" +# Used in sentences such as "All Tags" +[ui_all] +other = "todos" + # Footer text [footer_all_rights_reserved] other = "Todos os direitos reservados" @@ -25,7 +27,6 @@ other = "Todos os direitos reservados" [footer_privacy_policy] other = "Política de Privacidade" - # Post (blog, articles etc.) [post_byline_by] other = "Por" @@ -35,6 +36,8 @@ other = "Criado" other = "Última modificação" [post_edit_this] other = "Editar essa página" +[post_view_this] +other = "Ver origem da página" [post_create_child_page] other = "Criar uma subpágina" [post_create_issue] @@ -75,3 +78,13 @@ other = "If you want to get more involved by contributing to {{ .Site.Title }}, other = "You can find out how to contribute to {{ .Site.Title }} in our" [community_guideline] other = "Contribution Guidelines" + +# Feedback +[feedback_title] +other = "Feedback" +[feedback_question] +other = "Esta página foi útil?" +[feedback_positive] +other = "Sim" +[feedback_negative] +other = "Não" diff --git a/i18n/sr-cyrl.toml b/i18n/sr-cyrl.toml new file mode 100644 index 0000000000..0dfcf865a0 --- /dev/null +++ b/i18n/sr-cyrl.toml @@ -0,0 +1,90 @@ +# UI strings. Buttons and similar. + +[ui_pager_prev] +other = "Претходно" + +[ui_pager_next] +other = "Наредно" + +[ui_read_more] +other = "Прочитајте више" + +[ui_search] +other = "Претражите сајт…" + +# Used in sentences such as "Posted in News" +[ui_in] +other = "у" + +# Used in sentences such as "All Tags" +[ui_all] +other = "све" + +# Footer text +[footer_all_rights_reserved] +other = "Сва права задржана" + +[footer_privacy_policy] +other = "Политика приватности" + +# Post (blog, articles etc.) +[post_byline_by] +other = "Аутор" +[post_created] +other = "Креирано" +[post_last_mod] +other = "Последњи пут измењено" +[post_edit_this] +other = "Уредите ову страницу" +[post_view_this] +other = "Погледајте извор странице" +[post_create_child_page] +other = "Креирајте подстраницу" +[post_create_issue] +other = "Креирајте issue за документацију" +[post_create_project_issue] +other = "Креирајте issue за пројекат" +[post_posts_in] +other = "Објава у" +[post_reading_time] +other = "минута за читање" +[post_less_than_a_minute_read] +other = "мање од минута за читање" + +# Print support +[print_printable_section] +other = "Ово је вишестрани преглед за штампање ове секције." +[print_click_to_print] +other = "Кликните овде за штампање" +[print_show_regular] +other = "Повратак на обичан преглед ове странице" +[print_entire_section] +other = "Одштампајте читаву секцију" + +# Community +[community_join] +other = "Придружите се {{ .Site.Title }} заједници" +[community_introduce] +other = "{{ .Site.Title }} је open source пројекат којег свако у заједници може да користи, унапређује и да ужива у њему. Волели бисмо да нам се придружите! Овде се можете укључити како бисте сазнали шта се дешава." +[community_learn] +other = "Научите и повежите се" +[community_using] +other = "Већ користите или желите да почнете користити {{ .Site.Title }}? Сазнајте више:" +[community_develop] +other = "Развој и допринос" +[community_contribute] +other = "Ако желите да се више укључите у допринос на {{ .Site.Title }}, придружите нам се:" +[community_how_to] +other = "Можете сазнати како да допринесете на {{ .Site.Title }} у нашим" +[community_guideline] +other = "Смерницама за допринос" + +# Feedback +[feedback_title] +other = "Feedback" +[feedback_question] +other = "Да ли вам је ова страница била од помоћи?" +[feedback_positive] +other = "Да" +[feedback_negative] +other = "Не" diff --git a/i18n/sr-latn.toml b/i18n/sr-latn.toml new file mode 100644 index 0000000000..c64ae0541b --- /dev/null +++ b/i18n/sr-latn.toml @@ -0,0 +1,90 @@ +# UI strings. Buttons and similar. + +[ui_pager_prev] +other = "Prethodno" + +[ui_pager_next] +other = "Naredno" + +[ui_read_more] +other = "Pročitajte više" + +[ui_search] +other = "Pretražite sajt…" + +# Used in sentences such as "Posted in News" +[ui_in] +other = "u" + +# Used in sentences such as "All Tags" +[ui_all] +other = "sve" + +# Footer text +[footer_all_rights_reserved] +other = "Sva prava zadržana" + +[footer_privacy_policy] +other = "Politika privatnosti" + +# Post (blog, articles etc.) +[post_byline_by] +other = "Autor" +[post_created] +other = "Kreirano" +[post_last_mod] +other = "Poslednji put izmenjeno" +[post_edit_this] +other = "Uredite ovu stranicu" +[post_view_this] +other = "Pogledajte izvor stranice" +[post_create_child_page] +other = "Kreirajte podstranicu" +[post_create_issue] +other = "Kreirajte issue za dokumentaciju" +[post_create_project_issue] +other = "Kreirajte issue za projekat" +[post_posts_in] +other = "Objava u" +[post_reading_time] +other = "minuta za čitanje" +[post_less_than_a_minute_read] +other = "manje od minuta za čitanje" + +# Print support +[print_printable_section] +other = "Ovo je višestrani pregled za štampanje ove sekcije." +[print_click_to_print] +other = "Kliknite ovde za štampanje" +[print_show_regular] +other = "Povratak na običan pregled ove stranice" +[print_entire_section] +other = "Odštampajte čitavu sekciju" + +# Community +[community_join] +other = "Pridružite se {{ .Site.Title }} zajednici" +[community_introduce] +other = "{{ .Site.Title }} je open source projekat kojeg svako u zajednici može da koristi, unapređuje i da uživa u njemu. Voleli bismo da nam se pridružite! Ovde se možete uključiti kako biste saznali šta se dešava." +[community_learn] +other = "Naučite i povežite se" +[community_using] +other = "Već koristite ili želite da počnete koristiti {{ .Site.Title }}? Saznajte više:" +[community_develop] +other = "Razvoj i doprinos" +[community_contribute] +other = "Ako želite da se više uključite u doprinos na {{ .Site.Title }}, pridružite nam se:" +[community_how_to] +other = "Možete saznati kako da doprinesete na {{ .Site.Title }} u našim" +[community_guideline] +other = "Smernicama za doprinos" + +# Feedback +[feedback_title] +other = "Feedback" +[feedback_question] +other = "Da li vam je ova stranica bila od pomoći?" +[feedback_positive] +other = "Da" +[feedback_negative] +other = "Ne" diff --git a/i18n/uk.toml b/i18n/uk.toml index bcabd82141..2694f80a38 100644 --- a/i18n/uk.toml +++ b/i18n/uk.toml @@ -7,7 +7,7 @@ other = "Попередня" other = "Наступна" [ui_read_more] -other = "Детальніше" +other = "Читати далі" [ui_search] other = "Пошук по сайту…" @@ -18,64 +18,73 @@ other = "у" # Used in sentences such as "All Tags" [ui_all] -other = "все" +other = "всі" # Footer text [footer_all_rights_reserved] -other = "Усі права захищені" +other = "Усі права захищено" [footer_privacy_policy] other = "Політика конфіденційності" - # Post (blog, articles etc.) [post_byline_by] other = "Автор" [post_created] other = "Створено" [post_last_mod] -other = "Змінено" +other = "Востаннє змінено" [post_edit_this] -other = "Відредагувати сторінку" +other = "Редагувати цю сторінку" [post_view_this] -other = "Побачити джерело сторінки" +other = "Переглянути джерело сторінки" [post_create_child_page] -other = "Створити додаткову сторінку" +other = "Створити дочірню сторінку" [post_create_issue] -other = "Запропонувати змінення документації" +other = "Створити запит щодо документації" [post_create_project_issue] -other = "Запропонувати допрацювання по проекту" +other = "Створити запит щодо проєкту" [post_posts_in] -other = "Публикації у" +other = "Публікації в" [post_reading_time] -other = "хвилина читання" +other = "хв. читання" [post_less_than_a_minute_read] other = "менше хвилини" # Print support [print_printable_section] -other = "Це багатосторінковий друкований вигляд цього розділу." +other = "Це багатосторінкова версія цього розділу для друку." [print_click_to_print] -other = "Натисність щоб друкувати" +other = "Натисніть тут, щоб надрукувати" [print_show_regular] other = "Повернутися до звичайного перегляду сторінки" [print_entire_section] -other = "Друкувати увесь розділ" +other = "Надрукувати весь розділ" # Community [community_join] -other = "Приєднуйтесь до {{ .Site.Title }} спільноти" +other = "Приєднуйтесь до спільноти {{ .Site.Title }}" [community_introduce] -other = "{{ .Site.Title }} - це проект з відкритим кодом, який будь-хто в спільноті може використовувати, покращувати та насолоджуватися. Ми будемо раді бачити тебе з нами! Ось декілька опцій щоб знати що відбувається та залучитись." +other = "{{ .Site.Title }} — це проєкт з відкритим вихідним кодом, яким будь-хто зі спільноти може користуватися, покращувати та насолоджуватися. Ми будемо раді, якщо ви приєднаєтеся до нас! Ось кілька способів дізнатися, що відбувається, і взяти участь." [community_learn] -other = "Вивчай та Приєднуйся" +other = "Вивчайте та приєднуйтесь" [community_using] -other = "Користуєшся чи хотів би користуватись {{ .Site.Title }}? Дізнайся більше тут:" +other = "Використовуєте або хочете використовувати {{ .Site.Title }}? Дізнайтеся більше тут:" [community_develop] -other = "Розвивай та Роби внесок" +other = "Розробляйте та робіть внески" [community_contribute] -other = "Якщо хочеш бути більш залученим, роблячи внесок у {{ .Site.Title }}, приєднуйся до нас тут:" +other = "Хочете долучитися до розвитку {{ .Site.Title }} та зробити свій внесок? Приєднуйтеся до нас тут:" [community_how_to] -other = "Дізнайся як зробити внесок до цих документів в нашому" +other = "Дізнайтеся, як зробити внесок у {{ .Site.Title }} у наших" [community_guideline] -other = "Рекомендації щодо внеску" +other = "Настановах з внесків" + +# Feedback +[feedback_title] +other = "Зворотний зв’язок" +[feedback_question] +other = "Чи була ця сторінка корисною?" +[feedback_positive] +other = "Так" +[feedback_negative] +other = "Ні" diff --git a/i18n/zh-tw.toml b/i18n/zh-tw.toml index 80bbff59d2..8211a019f1 100644 --- a/i18n/zh-tw.toml +++ b/i18n/zh-tw.toml @@ -32,33 +32,33 @@ other = "隱私政策" [post_byline_by] other = "作者：" [post_created] -other = "創建" +other = "建立" [post_last_mod] -other = "最後修改" +other = "最後更新於" [post_edit_this] other = "編輯此頁" [post_view_this] -other = "查看頁面原始碼" +other = "檢視頁面原始碼" [post_create_child_page] -other = "創建子頁面" +other = "建立子頁面" [post_create_issue] -other = "創建文檔議題" +other = "建立文件議題" [post_create_project_issue] -other = "創建項目議題" +other = "建立專案議題" [post_posts_in] other = "張貼於" [post_reading_time] -other = " 分鐘左右可讀完" +other = " 分鐘閱讀時間" [post_less_than_a_minute_read] other = "1 分鐘內可讀完" # Print support [print_printable_section] -other = "這是本節的多頁可列印視圖。" +other = "這是本節的多頁可列印檢視。" [print_click_to_print] -other = "點擊此處列印" +other = "點選此處列印" [print_show_regular] -other = "返回此頁面的常規視圖" +other = "返回此頁面的標準檢視" [print_entire_section] other = "列印整個章節" @@ -66,16 +66,26 @@ other = "列印整個章節" [community_join] other = "加入 {{ .Site.Title }} 社群" [community_introduce] -other = "{{ .Site.Title }} 是一個開源項目，社群中的任何人都可以使用、改善和盡情使用它。我們很期待你能加入我們！下面是如何查看最近更新以及參與我們的一些方式。" +other = "{{ .Site.Title }} 是一個開放原始碼專案，社群中的任何人都可以使用、改進並享受其成果。我們非常歡迎您加入我們！以下是了解最新動態以及參與我們的一些方式。" [community_learn] -other = "學習和溝通" +other = "學習與交流" [community_using] -other = "正在或打算使用 {{ .Site.Title }} ？獲取更多資訊：" +other = "正在或打算使用 {{ .Site.Title }} 嗎？在此取得更多資訊：" [community_develop] other = "開發和貢獻" [community_contribute] -other = "如果你想通過為 {{ .Site.Title }} 貢獻更多參與，請在此處加入我們：" +other = "如果您想透過貢獻來更深入地參與 {{ .Site.Title }}，請在此處加入我們：" [community_how_to] -other = "你可以了解如何為 {{ .Site.Title }} 做出貢獻，請參考我們的" +other = "您可以透過文件了解如何為 {{ .Site.Title }} 做出貢獻，請參考我們的" [community_guideline] other = "貢獻指南" + +# Feedback +[feedback_title] +other = "意見回饋" +[feedback_question] +other = "這個頁面對您有幫助嗎？" +[feedback_positive] +other = "有幫助" +[feedback_negative] +other = "沒幫助" diff --git a/layouts/_default/_markup/td-render-heading.html b/layouts/_default/_markup/td-render-heading.html deleted file mode 100644 index 9b470cede5..0000000000 --- a/layouts/_default/_markup/td-render-heading.html +++ /dev/null @@ -1,8 +0,0 @@ - - {{- .Text | safeHTML -}} - {{ template "_default/_markup/_td-heading-self-link.html" . -}} - - -{{- define "_default/_markup/_td-heading-self-link.html" -}} - -{{- end -}} diff --git a/layouts/_default/list.rss.xml b/layouts/_default/list.rss.xml deleted file mode 100644 index b74bc35794..0000000000 --- a/layouts/_default/list.rss.xml +++ /dev/null @@ -1,43 +0,0 @@ - - - {{ .Site.Title }} – {{ .Title }} - {{ .Permalink }} - Recent content {{ if ne .Title .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }} - Hugo -- gohugo.io{{ with .Site.LanguageCode }} - {{.}}{{end}}{{ with .Site.Author.email }} - {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Author.email }} - {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Copyright }} - {{.}}{{end}}{{ if not .Date.IsZero }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}{{ end }} - {{ with .OutputFormats.Get "RSS" }} - {{ printf "" .Permalink .MediaType | safeHTML }} - {{ end }} - {{ if not $.Section }} - {{ $sections := .Site.Params.rss_sections | default (slice "blog") }} - {{ .Scratch.Set "rss_pages" (first 50 (where $.Site.RegularPages "Type" "in" $sections )) }} - {{ else }} - {{ if $.Parent.IsHome }} - {{ .Scratch.Set "rss_pages" (first 50 (where $.Site.RegularPages "Type" $.Section )) }} - {{ else }} - {{ .Scratch.Set "rss_pages" (first 50 $.Pages) }} - {{ end }} - {{ end }} - {{ range (.Scratch.Get "rss_pages") }} - - {{ .Section | title }}: {{ .Title }} - {{ .Permalink }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} - {{ with .Site.Author.email }}{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}} - {{ .Permalink }} - - {{ $img := (.Resources.ByType "image").GetMatch "*featured*" }} - {{ with $img }} - {{ $img := .Resize "640x" }} - {{ printf "]]>" $img.Permalink $img.Width $img.Height | safeHTML }} - {{ end }} - {{ .Content | html }} - - - {{ end }} - - diff --git a/layouts/_default/single.html b/layouts/_default/single.html deleted file mode 100644 index 8362338e45..0000000000 --- a/layouts/_default/single.html +++ /dev/null @@ -1,3 +0,0 @@ -{{ define "main" -}} -{{ .Content -}} -{{ end }} diff --git a/layouts/_internal/google_analytics_gtag.html b/layouts/_internal/google_analytics_gtag.html deleted file mode 100644 index 2c9c7da908..0000000000 --- a/layouts/_internal/google_analytics_gtag.html +++ /dev/null @@ -1,42 +0,0 @@ -{{/* - - This is a modified copy of - - https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/google_analytics.html, - - specifically this version: - - https://github.com/gohugoio/hugo/blob/8d32ca223def4031aa26f98e8efc1a8b4e7b7546/tpl/tplimpl/embedded/templates/google_analytics.html - - The only differences between this copy and the original are that we've dropped: - - - The `{{ if hasPrefix . "G-"}}` condition - - The `{{ else ... }}` block - - The `anonymize_ip` argument to the `gtag()` call, since it is superfluous. - For details, see https://github.com/gohugoio/hugo/issues/10093. - -*/}} - -{{- $pc := .Site.Config.Privacy.GoogleAnalytics -}} -{{- if not $pc.Disable }}{{ with .Site.Config.Services.GoogleAnalytics.ID -}} - - -{{- end }}{{ end -}} - -{{- define "__ga_js_set_doNotTrack" -}}{{/* This is also used in the async version. */}} -{{- $pc := .Site.Config.Privacy.GoogleAnalytics -}} -{{- if not $pc.RespectDoNotTrack -}} -var doNotTrack = false; -{{- else -}} -var dnt = (navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack); -var doNotTrack = (dnt == "1" || dnt == "yes"); -{{- end -}} -{{- end -}} \ No newline at end of file diff --git a/layouts/_default/_markup/render-codeblock-chem.html b/layouts/_markup/render-codeblock-chem.html similarity index 100% rename from layouts/_default/_markup/render-codeblock-chem.html rename to layouts/_markup/render-codeblock-chem.html diff --git a/layouts/_default/_markup/render-codeblock-math.html b/layouts/_markup/render-codeblock-math.html similarity index 100% rename from layouts/_default/_markup/render-codeblock-math.html rename to layouts/_markup/render-codeblock-math.html diff --git a/layouts/_default/_markup/render-codeblock-mermaid.html b/layouts/_markup/render-codeblock-mermaid.html similarity index 100% rename from layouts/_default/_markup/render-codeblock-mermaid.html rename to layouts/_markup/render-codeblock-mermaid.html diff --git a/layouts/partials/breadcrumb.html b/layouts/_partials/breadcrumb.html similarity index 100% rename from layouts/partials/breadcrumb.html rename to layouts/_partials/breadcrumb.html diff --git a/layouts/partials/community_links.html b/layouts/_partials/community_links.html similarity index 84% rename from layouts/partials/community_links.html rename to layouts/_partials/community_links.html index 4f0505ebc2..7a033fc395 100644 --- a/layouts/partials/community_links.html +++ b/layouts/_partials/community_links.html @@ -1,4 +1,5 @@ {{ $links := .Site.Params.links -}} +{{ $contribUrl := .Params.contributingUrl | default "docs/contribution-guidelines" -}}
@@ -16,7 +17,7 @@

{{ T "community_develop" }}

{{ end }}

{{ T "community_how_to" . }} - {{ T "community_guideline" }}. + {{ T "community_guideline" }}.

diff --git a/layouts/partials/disqus-comment.html b/layouts/_partials/disqus-comment.html similarity index 100% rename from layouts/partials/disqus-comment.html rename to layouts/_partials/disqus-comment.html diff --git a/layouts/partials/favicons.html b/layouts/_partials/favicons.html similarity index 100% rename from layouts/partials/favicons.html rename to layouts/_partials/favicons.html diff --git a/layouts/partials/featured-image.html b/layouts/_partials/featured-image.html similarity index 100% rename from layouts/partials/featured-image.html rename to layouts/_partials/featured-image.html diff --git a/layouts/partials/feedback.html b/layouts/_partials/feedback.html similarity index 100% rename from layouts/partials/feedback.html rename to layouts/_partials/feedback.html diff --git a/layouts/partials/footer.html b/layouts/_partials/footer.html similarity index 100% rename from layouts/partials/footer.html rename to layouts/_partials/footer.html diff --git a/layouts/partials/footer/center.html b/layouts/_partials/footer/center.html similarity index 100% rename from layouts/partials/footer/center.html rename to layouts/_partials/footer/center.html diff --git a/layouts/partials/footer/copyright.html b/layouts/_partials/footer/copyright.html similarity index 89% rename from layouts/partials/footer/copyright.html rename to layouts/_partials/footer/copyright.html index 8962fb87aa..1370c5e1f4 100644 --- a/layouts/partials/footer/copyright.html +++ b/layouts/_partials/footer/copyright.html @@ -33,8 +33,9 @@ {{- else -}} {{ with .Site.Copyright -}} + {{/* For historical reasons we process this as HTML rather than markdown. */ -}} - {{- . | $page.RenderString -}} + {{- . | safeHTML -}} {{- end -}} diff --git a/layouts/partials/footer/left.html b/layouts/_partials/footer/left.html similarity index 100% rename from layouts/partials/footer/left.html rename to layouts/_partials/footer/left.html diff --git a/layouts/partials/footer/links.html b/layouts/_partials/footer/links.html similarity index 100% rename from layouts/partials/footer/links.html rename to layouts/_partials/footer/links.html diff --git a/layouts/partials/footer/right.html b/layouts/_partials/footer/right.html similarity index 100% rename from layouts/partials/footer/right.html rename to layouts/_partials/footer/right.html diff --git a/layouts/_partials/head-css.html b/layouts/_partials/head-css.html new file mode 100644 index 0000000000..ba2a48829c --- /dev/null +++ b/layouts/_partials/head-css.html @@ -0,0 +1,30 @@ +{{ $scssMain := "scss/main.scss" -}} +{{ $css := resources.Get $scssMain + | toCSS (dict "enableSourceMap" (not hugo.IsProduction)) -}} + +{{/* NOTE: we only apply `postCSS` in production or for RTL languages. This +makes it snappier to develop in Chrome, but it may look sub-optimal in other +browsers. */ -}} + +{{ if eq .Site.Language.LanguageDirection "rtl" -}} + {{ $css = $css + | postCSS (dict "use" "autoprefixer rtlcss" "noMap" true) + | resources.Copy (replace $scssMain "." ".rtl.") -}} +{{ else if hugo.IsProduction -}} + {{ $css = $css | postCSS -}} +{{ end -}} + +{{ if hugo.IsProduction -}} + {{ $css = $css | minify | fingerprint -}} + +{{ end -}} + +{{ with $css -}} + +{{ else -}} + {{ errorf "Resource not found or error building CSS: %s" $scssMain -}} +{{ end -}} + +{{- /**/ -}} diff --git a/layouts/partials/head.html b/layouts/_partials/head.html similarity index 72% rename from layouts/partials/head.html rename to layouts/_partials/head.html index ec4525dafe..d25e217128 100644 --- a/layouts/partials/head.html +++ b/layouts/_partials/head.html @@ -1,3 +1,4 @@ +{{/* cSpell:ignore docsearch opengraph outputformat */ -}} {{ range .AlternativeOutputFormats -}} @@ -20,11 +21,11 @@ {{ .Site.Title -}} {{ end -}} - -{{ template "_internal/opengraph.html" . -}} -{{ template "_internal/schema.html" . -}} -{{ template "_internal/twitter_cards.html" . -}} -{{ partialCached "head-css.html" . "asdf" -}} + +{{ partial "opengraph.html" . -}} +{{ partial "schema.html" . -}} +{{ partial "twitter_cards.html" . -}} +{{ partialCached "head-css.html" . "head-css-cache-key" -}} {{ end -}} -{{ if $needKaTeX -}} -{{/* load stylesheet and scripts for KaTeX support */ -}} - - {{/* The loading of KaTeX is deferred to speed up page rendering */ -}} - - {{ if $needmhchem -}} - {{/* To add support for displaying chemical equations and physical units, load the mhchem extension: */ -}} - - {{ end -}} - {{/* To automatically render math in text elements, include the auto-render extension: */ -}} - +{{ if $needKaTeX -}} + {{ partial "scripts/katex.html" (dict "mhchem" $needmhchem) -}} {{ end -}} {{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}} @@ -101,11 +74,16 @@ {{ template "algolia/scripts" .Site.Params.search.algolia -}} {{ end -}} + +{{ if .Site.Params.jstoc.enable -}} +{{- partial "scripts/jstoc.html" . -}} +{{ end -}} + {{ partial "hooks/body-end.html" . -}} {{ define "algolia/scripts" -}} - + {{ end -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid Tocbot version %s, could not retrieve this version from CDN." $version -}} +{{ end -}} + + + diff --git a/layouts/_partials/scripts/katex.html b/layouts/_partials/scripts/katex.html new file mode 100644 index 0000000000..c29b436785 --- /dev/null +++ b/layouts/_partials/scripts/katex.html @@ -0,0 +1,55 @@ +{{ $version := .Site.Params.katex.version | default "latest" -}} + +{{/* load stylesheet and scripts for KaTeX support */ -}} +{{ $katex_css_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex%s.css" $version (cond hugo.IsProduction ".min" "") -}} + +{{ with try (resources.GetRemote $katex_css_url) -}} + {{ with .Err -}} + {{ errorf "Could not retrieve KaTeX css file from CDN. Reason: %s." . -}} + {{ else with.Value -}} + {{ with resources.Copy (printf "css/katex%s.css" (cond hugo.IsProduction ".min" "")) . }} + {{ $secureCSS := . | resources.Fingerprint "sha512" -}} + + {{ end -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}} +{{ end -}} + +{{/* The loading of KaTeX is deferred to speed up page rendering */ -}} +{{ $katex_js_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex%s.js" $version (cond hugo.IsProduction ".min" "") -}} +{{ with try (resources.GetRemote $katex_js_url) -}} + {{ with .Err -}} + {{ errorf "Could not retrieve KaTeX script from CDN. Reason: %s." . -}} + {{ else with.Value -}} + {{ with resources.Copy (printf "js/katex%s.js" (cond hugo.IsProduction ".min" "")) . }} + {{ $secureJS := . | resources.Fingerprint "sha512" -}} + + {{ end -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}} +{{ end -}} + +{{/* Add support for displaying chemical equations and physical units by loading the mhchem extension: */ -}} +{{ if .mhchem -}} +{{ partial "scripts/mhchem.html" (dict "version" $version) -}} +{{ end -}} + +{{/* To automatically render math in text elements, include the auto-render extension: */ -}} + +{{ $katex_autorender_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/contrib/auto-render%s.js" $version (cond hugo.IsProduction ".min" "") -}} +{{ with try (resources.GetRemote $katex_autorender_url) -}} + {{ with .Err -}} + {{ errorf "Could not retrieve KaTeX auto render extension from CDN. Reason: %s." . -}} + {{ else with .Value -}} + {{ with resources.Copy ( printf "js/auto-render%s.js" (cond hugo.IsProduction ".min" "")) . }} + {{ $secureJS := . | resources.Fingerprint "sha512" -}} + + {{ end -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}} +{{ end -}} diff --git a/layouts/_partials/scripts/mermaid.html b/layouts/_partials/scripts/mermaid.html new file mode 100644 index 0000000000..99f7fbe08f --- /dev/null +++ b/layouts/_partials/scripts/mermaid.html @@ -0,0 +1,67 @@ +{{ $version := .Site.Params.mermaid.version | default "latest" -}} + +{{ $cdnurl := printf "https://cdn.jsdelivr.net/npm/mermaid@%s/dist/mermaid.esm.min.mjs" $version -}} +{{ with try (resources.GetRemote $cdnurl) -}} + {{ with .Err -}} + {{ errorf "Could not retrieve mermaid script from CDN. Reason: %s." . -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid Mermaid version %s, could not retrieve this version from CDN." $version -}} +{{ end -}} + + diff --git a/layouts/_partials/scripts/mhchem.html b/layouts/_partials/scripts/mhchem.html new file mode 100644 index 0000000000..931ca4ddbb --- /dev/null +++ b/layouts/_partials/scripts/mhchem.html @@ -0,0 +1,14 @@ +{{/* Add support for displaying chemical equations and physical units by loading the mhchem extension: */ -}} +{{ $mhchem_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/contrib/mhchem%s.js" .version (cond hugo.IsProduction ".min" "") -}} +{{ with try (resources.GetRemote $mhchem_url) -}} + {{ with .Err -}} + {{ errorf "Could not retrieve mhchem script from CDN. Reason: %s." . -}} + {{ else with .Value -}} + {{ with resources.Copy (printf "js/mhchem%s.js" (cond hugo.IsProduction ".min" "")) . }} + {{ $secureJS := . | resources.Fingerprint "sha512" -}} + + {{ end -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." .version -}} +{{ end -}} diff --git a/layouts/partials/search-input.html b/layouts/_partials/search-input.html similarity index 100% rename from layouts/partials/search-input.html rename to layouts/_partials/search-input.html diff --git a/layouts/partials/section-index.html b/layouts/_partials/section-index.html similarity index 90% rename from layouts/partials/section-index.html rename to layouts/_partials/section-index.html index 0ce414e74d..685dde8a50 100644 --- a/layouts/partials/section-index.html +++ b/layouts/_partials/section-index.html @@ -1,16 +1,16 @@
- {{ $parent := .Page -}} + {{ $page := .Page -}} {{ $pages := (where .Site.Pages "Section" .Section).ByWeight -}} {{ $pages = (where $pages "Type" "!=" "search") }} {{ $pages = (where $pages ".Params.hide_summary" "!=" true) -}} {{ $pages = (where $pages ".Parent" "!=" nil) -}} {{ $pages = (where $pages ".Parent.File" "!=" nil) -}} - {{ if and $parent $parent.File -}} - {{ $pages = (where $pages "Parent.File.UniqueID" "==" $parent.File.UniqueID) -}} + {{ if $page.File -}} + {{ $pages = (where $pages "Parent.File.UniqueID" "==" $page.File.UniqueID) -}} {{ end -}} - {{ if or $parent.Params.no_list (eq (len $pages) 0) -}} + {{ if or $page.Params.no_list (eq (len $pages) 0) -}} {{/* If no_list is true or we don't have subpages we don't show a list of subpages */}} - {{ else if $parent.Params.simple_list -}} + {{ else if $page.Params.simple_list -}} {{/* If simple_list is true we show a bulleted list of subpages */}} {{- end }} -{{- end }} \ No newline at end of file +{{- end -}} diff --git a/layouts/partials/sidebar.html b/layouts/_partials/sidebar.html similarity index 100% rename from layouts/partials/sidebar.html rename to layouts/_partials/sidebar.html diff --git a/layouts/partials/taxonomy_terms_article.html b/layouts/_partials/taxonomy_terms_article.html similarity index 100% rename from layouts/partials/taxonomy_terms_article.html rename to layouts/_partials/taxonomy_terms_article.html diff --git a/layouts/partials/taxonomy_terms_article_wrapper.html b/layouts/_partials/taxonomy_terms_article_wrapper.html similarity index 100% rename from layouts/partials/taxonomy_terms_article_wrapper.html rename to layouts/_partials/taxonomy_terms_article_wrapper.html diff --git a/layouts/partials/taxonomy_terms_cloud.html b/layouts/_partials/taxonomy_terms_cloud.html similarity index 100% rename from layouts/partials/taxonomy_terms_cloud.html rename to layouts/_partials/taxonomy_terms_cloud.html diff --git a/layouts/partials/taxonomy_terms_clouds.html b/layouts/_partials/taxonomy_terms_clouds.html similarity index 100% rename from layouts/partials/taxonomy_terms_clouds.html rename to layouts/_partials/taxonomy_terms_clouds.html diff --git a/layouts/_partials/td/render-heading.html b/layouts/_partials/td/render-heading.html new file mode 100644 index 0000000000..bbb9942a81 --- /dev/null +++ b/layouts/_partials/td/render-heading.html @@ -0,0 +1,12 @@ + + {{- .Text | safeHTML -}} + {{ partial "td/heading-self-link.html" . -}} + + +{{- define "_partials/td/heading-self-link.html" -}} + +{{- end -}} diff --git a/layouts/partials/theme-toggler.html b/layouts/_partials/theme-toggler.html similarity index 100% rename from layouts/partials/theme-toggler.html rename to layouts/_partials/theme-toggler.html diff --git a/layouts/partials/toc.html b/layouts/_partials/toc.html similarity index 100% rename from layouts/partials/toc.html rename to layouts/_partials/toc.html diff --git a/layouts/partials/version-banner.html b/layouts/_partials/version-banner.html similarity index 100% rename from layouts/partials/version-banner.html rename to layouts/_partials/version-banner.html diff --git a/layouts/shortcodes/alert.html b/layouts/_shortcodes/alert.html similarity index 100% rename from layouts/shortcodes/alert.html rename to layouts/_shortcodes/alert.html diff --git a/layouts/shortcodes/blocks/cover.html b/layouts/_shortcodes/blocks/cover.html similarity index 100% rename from layouts/shortcodes/blocks/cover.html rename to layouts/_shortcodes/blocks/cover.html diff --git a/layouts/shortcodes/blocks/feature.html b/layouts/_shortcodes/blocks/feature.html similarity index 100% rename from layouts/shortcodes/blocks/feature.html rename to layouts/_shortcodes/blocks/feature.html diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/_shortcodes/blocks/lead.html similarity index 100% rename from layouts/shortcodes/blocks/lead.html rename to layouts/_shortcodes/blocks/lead.html diff --git a/layouts/shortcodes/blocks/link-down.html b/layouts/_shortcodes/blocks/link-down.html similarity index 100% rename from layouts/shortcodes/blocks/link-down.html rename to layouts/_shortcodes/blocks/link-down.html diff --git a/layouts/shortcodes/blocks/section.html b/layouts/_shortcodes/blocks/section.html similarity index 100% rename from layouts/shortcodes/blocks/section.html rename to layouts/_shortcodes/blocks/section.html diff --git a/layouts/shortcodes/card.html b/layouts/_shortcodes/card.html similarity index 100% rename from layouts/shortcodes/card.html rename to layouts/_shortcodes/card.html diff --git a/layouts/shortcodes/cardpane.html b/layouts/_shortcodes/cardpane.html similarity index 100% rename from layouts/shortcodes/cardpane.html rename to layouts/_shortcodes/cardpane.html diff --git a/layouts/_shortcodes/comment.html b/layouts/_shortcodes/comment.html new file mode 100644 index 0000000000..fa48a06083 --- /dev/null +++ b/layouts/_shortcodes/comment.html @@ -0,0 +1,8 @@ +{{/* Allows for large segments of Markdown or HTML to be commented out. This was +briefly an internal Hugo template, but it is no more. For details, see: + +- https://discourse.gohugo.io/t/deprecate-comment-shortcode/53237 +- https://github.com/gohugoio/hugo/pull/13294 + +*/}} +{{- $noop := .Inner -}} diff --git a/layouts/shortcodes/conditional-text.html b/layouts/_shortcodes/conditional-text.html similarity index 100% rename from layouts/shortcodes/conditional-text.html rename to layouts/_shortcodes/conditional-text.html diff --git a/layouts/shortcodes/iframe.html b/layouts/_shortcodes/iframe.html similarity index 100% rename from layouts/shortcodes/iframe.html rename to layouts/_shortcodes/iframe.html diff --git a/layouts/shortcodes/imgproc.html b/layouts/_shortcodes/imgproc.html similarity index 100% rename from layouts/shortcodes/imgproc.html rename to layouts/_shortcodes/imgproc.html diff --git a/layouts/shortcodes/pageinfo.html b/layouts/_shortcodes/pageinfo.html similarity index 100% rename from layouts/shortcodes/pageinfo.html rename to layouts/_shortcodes/pageinfo.html diff --git a/layouts/shortcodes/readfile.html b/layouts/_shortcodes/readfile.html similarity index 100% rename from layouts/shortcodes/readfile.html rename to layouts/_shortcodes/readfile.html diff --git a/layouts/shortcodes/redoc.html b/layouts/_shortcodes/redoc.html similarity index 100% rename from layouts/shortcodes/redoc.html rename to layouts/_shortcodes/redoc.html diff --git a/layouts/shortcodes/swaggerui.html b/layouts/_shortcodes/swaggerui.html similarity index 100% rename from layouts/shortcodes/swaggerui.html rename to layouts/_shortcodes/swaggerui.html diff --git a/layouts/shortcodes/tab.html b/layouts/_shortcodes/tab.html similarity index 100% rename from layouts/shortcodes/tab.html rename to layouts/_shortcodes/tab.html diff --git a/layouts/shortcodes/tabpane.html b/layouts/_shortcodes/tabpane.html similarity index 98% rename from layouts/shortcodes/tabpane.html rename to layouts/_shortcodes/tabpane.html index 8b0156618d..8edb4b7544 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/_shortcodes/tabpane.html @@ -126,7 +126,7 @@ {{ if $duplicate -}} - {{ warnf "Shortcode %q: duplicate tab-persistence key %q detected, disabling persistance to avoid multiple tab display. Position: %s" $.Name $duplicateKey $.Position -}} + {{ warnf "Shortcode %q: duplicate tab-persistence key %q detected, disabling persistence to avoid multiple tab display. Position: %s" $.Name $duplicateKey $.Position -}} {{ end -}} {{ $activeSet = false -}} diff --git a/layouts/_td-content-after-header.html b/layouts/_td-content-after-header.html new file mode 100644 index 0000000000..e69de29bb2 diff --git a/layouts/_default/content.html b/layouts/_td-content.html similarity index 93% rename from layouts/_default/content.html rename to layouts/_td-content.html index 728d237750..f58b4ce6af 100644 --- a/layouts/_default/content.html +++ b/layouts/_td-content.html @@ -7,6 +7,7 @@

{{ .Title }}

{{ partial "reading-time.html" . -}} {{ end -}} + {{ .Render "_td-content-after-header" -}} {{ .Content }} {{ partial "feedback.html" . -}} {{ if (.Site.Config.Services.Disqus.Shortname) -}} diff --git a/layouts/_default/list.html b/layouts/all.html similarity index 100% rename from layouts/_default/list.html rename to layouts/all.html diff --git a/layouts/_default/baseof.html b/layouts/baseof.html similarity index 67% rename from layouts/_default/baseof.html rename to layouts/baseof.html index 29ad5768d7..e390629146 100644 --- a/layouts/_default/baseof.html +++ b/layouts/baseof.html @@ -1,5 +1,8 @@ - + {{ partial "head.html" . }} diff --git a/layouts/blog/content.html b/layouts/blog/_td-content.html similarity index 95% rename from layouts/blog/content.html rename to layouts/blog/_td-content.html index dbb6559135..61694a5a7e 100644 --- a/layouts/blog/content.html +++ b/layouts/blog/_td-content.html @@ -11,6 +11,7 @@

{{ .Title }}

{{ partial "reading-time.html" . -}} {{ end -}} + {{ .Render "_td-content-after-header" -}} {{ .Content }} {{ if (.Site.Config.Services.Disqus.Shortname) -}}
diff --git a/layouts/blog/baseof.html b/layouts/blog/baseof.html index b378805af6..5920353c87 100644 --- a/layouts/blog/baseof.html +++ b/layouts/blog/baseof.html @@ -1,5 +1,8 @@ - + {{ partial "head.html" . }} @@ -24,6 +27,9 @@ {{ end -}} + {{ if not (.Param "ui.breadcrumb_disable") -}} + {{ partial "breadcrumb.html" . -}} + {{ end -}} {{ block "main" . }}{{ end }}
diff --git a/layouts/blog/baseof.print.html b/layouts/blog/baseof.print.html index 99e3c1c4d1..21e63c5f79 100644 --- a/layouts/blog/baseof.print.html +++ b/layouts/blog/baseof.print.html @@ -1,5 +1,8 @@ - + {{ partial "head.html" . }} diff --git a/layouts/blog/list.html b/layouts/blog/list.html index 43f536ae9c..e0e0a2c000 100644 --- a/layouts/blog/list.html +++ b/layouts/blog/list.html @@ -1,40 +1,45 @@ -{{ define "main" }} +{{ define "main" -}} + +
+

{{ .Title }}

+{{ with .Content }}{{ . }}{{ end -}} +
{{ if (and .Parent .Parent.IsHome) -}} {{ $.Scratch.Set "blog-pages" (where .Site.RegularPages "Section" .Section) -}} {{ else -}} {{$.Scratch.Set "blog-pages" .Pages -}} {{ end -}} +{{ if .Pages -}}
- {{ if .Pages -}} - {{ $pag := .Paginate (( $.Scratch.Get "blog-pages").GroupByDate "2006" ) -}} - {{ range $pag.PageGroups -}} -
{{ T "post_posts_in" }} {{ .Key }}
- + {{ $pager := .Paginate (( $.Scratch.Get "blog-pages").GroupByDate "2006" ) -}} + {{ range $pager.PageGroups -}} +
{{ T "post_posts_in" }} {{ .Key }}
+ + {{ end -}}
- {{ if .Pages -}} - {{ template "_internal/pagination.html" . -}} - {{ end -}} + {{ partial "pagination.html" . -}}
+{{- end -}} {{ end -}} diff --git a/layouts/blog/single.html b/layouts/blog/single.html index 00cb3ab911..d82608611a 100644 --- a/layouts/blog/single.html +++ b/layouts/blog/single.html @@ -1,3 +1,3 @@ {{ define "main" }} -{{ .Render "content" }} +{{ .Render "_td-content" }} {{ end }} \ No newline at end of file diff --git a/layouts/docs/baseof.html b/layouts/docs/baseof.html index 210b6af52a..c91b2303de 100644 --- a/layouts/docs/baseof.html +++ b/layouts/docs/baseof.html @@ -1,5 +1,8 @@ - + {{ partial "head.html" . }} @@ -20,7 +23,9 @@
{{ partial "version-banner.html" . }} - {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} + {{ if not (.Param "ui.breadcrumb_disable") -}} + {{ partial "breadcrumb.html" . -}} + {{ end -}} {{ block "main" . }}{{ end }}
diff --git a/layouts/docs/baseof.print.html b/layouts/docs/baseof.print.html index 41e0659b3e..e839aa946c 100644 --- a/layouts/docs/baseof.print.html +++ b/layouts/docs/baseof.print.html @@ -1,5 +1,8 @@ - + {{ partial "head.html" . }} diff --git a/layouts/docs/list.html b/layouts/docs/list.html index 9ba3e31e80..0f96f57771 100644 --- a/layouts/docs/list.html +++ b/layouts/docs/list.html @@ -8,8 +8,9 @@

{{ .Title }}

{{ partial "reading-time.html" . -}} {{ end -}} + {{ .Render "_td-content-after-header" -}} {{ .Content }} - {{ partial "section-index.html" . -}} + {{ partial "section-index.html" . -}} {{ partial "feedback.html" . -}} {{ if (.Site.Config.Services.Disqus.Shortname) -}}
diff --git a/layouts/docs/single.html b/layouts/docs/single.html index 00cb3ab911..d82608611a 100644 --- a/layouts/docs/single.html +++ b/layouts/docs/single.html @@ -1,3 +1,3 @@ {{ define "main" }} -{{ .Render "content" }} +{{ .Render "_td-content" }} {{ end }} \ No newline at end of file diff --git a/layouts/home.html b/layouts/home.html deleted file mode 100644 index b2e137af6f..0000000000 --- a/layouts/home.html +++ /dev/null @@ -1,5 +0,0 @@ -{{ define "main" }} -{{ with .Content }} -{{ . }} -{{ end }} -{{ end }} \ No newline at end of file diff --git a/layouts/partials/head-css.html b/layouts/partials/head-css.html deleted file mode 100644 index d2178317d4..0000000000 --- a/layouts/partials/head-css.html +++ /dev/null @@ -1,11 +0,0 @@ - -{{ $scssMain := "scss/main.scss"}} -{{ if not hugo.IsProduction }} -{{/* Note the missing postCSS. This makes it snappier to develop in Chrome, but makes it look sub-optimal in other browsers. */}} -{{ $css := resources.Get $scssMain | toCSS (dict "enableSourceMap" true) }} - -{{ else }} -{{ $css := resources.Get $scssMain | toCSS (dict "enableSourceMap" false) | postCSS | minify | fingerprint }} - - -{{ end }} diff --git a/layouts/partials/page-description.html b/layouts/partials/page-description.html deleted file mode 100644 index 3529fbe611..0000000000 --- a/layouts/partials/page-description.html +++ /dev/null @@ -1,11 +0,0 @@ -{{ with .Description | plainify -}} - {{ . -}} -{{ else -}} - {{ if .IsPage -}} - {{ .Summary | plainify | chomp -}} - {{ else -}} - {{ with .Site.Params.description | plainify -}} - {{ . -}} - {{ end -}} - {{ end -}} -{{ end -}} diff --git a/layouts/partials/scripts/mermaid.html b/layouts/partials/scripts/mermaid.html deleted file mode 100644 index 6ea757a8df..0000000000 --- a/layouts/partials/scripts/mermaid.html +++ /dev/null @@ -1,44 +0,0 @@ -{{ $version := .Site.Params.mermaid.version | default "latest" -}} - -{{ $cdnurl := printf "https://cdn.jsdelivr.net/npm/mermaid@%s/dist/mermaid.esm.min.mjs" $version -}} -{{ with resources.GetRemote $cdnurl -}} - {{ with .Err -}} - {{ errorf "Could not retrieve mermaid script from CDN. Reason: %s." . -}} - {{ end -}} -{{ else -}} - {{ errorf "Invalid Mermaid version %s, could not retrieve this version from CDN." $version -}} -{{ end -}} - - diff --git a/layouts/_default/search.html b/layouts/search.html similarity index 100% rename from layouts/_default/search.html rename to layouts/search.html diff --git a/layouts/shortcodes/figure.html b/layouts/shortcodes/figure.html deleted file mode 100644 index 8d126f065d..0000000000 --- a/layouts/shortcodes/figure.html +++ /dev/null @@ -1,29 +0,0 @@ -{{ $src := (.Page.Resources.GetMatch (printf "**%s*" (.Get "src"))) }} - - {{- if .Get "link" -}} - - {{- end }} - {{ with .Get - {{- if .Get "link" }}{{ end -}} - {{- if or (or (.Get "title") (.Get "caption")) (.Get "attr") -}} -
- {{ with (.Get "title") -}} -

{{ . }}

- {{- end -}} - {{- if or (.Get "caption") (.Get "attr") -}}

- {{- .Get "caption" | markdownify -}} - {{- with .Get "attrlink" }} - - {{- end -}} - {{- .Get "attr" | markdownify -}} - {{- if .Get "attrlink" }}{{ end }}

- {{- end }} -
- {{- end }} - diff --git a/layouts/swagger/baseof.html b/layouts/swagger/baseof.html index 7a68c0c8e2..b338a58181 100644 --- a/layouts/swagger/baseof.html +++ b/layouts/swagger/baseof.html @@ -1,9 +1,12 @@ - + {{ partial "head.html" . }} {{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }} - +
@@ -21,9 +24,11 @@ {{ partial "taxonomy_terms_clouds.html" . }}
- {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} - - + {{ if not (.Param "ui.breadcrumb_disable") -}} + {{ partial "breadcrumb.html" . -}} + {{ end -}} + + {{ block "main" . }}{{ end }}
diff --git a/layouts/swagger/single.html b/layouts/swagger/single.html index 00cb3ab911..d82608611a 100644 --- a/layouts/swagger/single.html +++ b/layouts/swagger/single.html @@ -1,3 +1,3 @@ {{ define "main" }} -{{ .Render "content" }} +{{ .Render "_td-content" }} {{ end }} \ No newline at end of file diff --git a/layouts/_default/terms.html b/layouts/taxonomy.html similarity index 100% rename from layouts/_default/terms.html rename to layouts/taxonomy.html diff --git a/layouts/_default/taxonomy.html b/layouts/term.html similarity index 98% rename from layouts/_default/taxonomy.html rename to layouts/term.html index ff6b8deef8..847e55e29a 100644 --- a/layouts/_default/taxonomy.html +++ b/layouts/term.html @@ -1,4 +1,4 @@ -{{ define "main" }} +{{ define "main" -}}

{{ with .Data.Singular }}{{ . | humanize }}: {{ end }}{{ .Title }}

@@ -29,4 +29,4 @@

{{ humanize ( T "ui_all" ) }} {{ with .Data.Plural }}{{ . | humanize }}{{ end }}

-{{ end }} +{{- end }} diff --git a/netlify.toml b/netlify.toml index faebe858a0..442d5a2167 100644 --- a/netlify.toml +++ b/netlify.toml @@ -6,7 +6,7 @@ publish = "userguide/public" command = "npm run docs-install && npm run build:preview" [build.environment] -GO_VERSION = "1.21.6" +GO_VERSION = "1.23.5" HUGO_THEME = "repo" [context.production] diff --git a/package.json b/package.json index efd6f08401..d855a0b5cc 100644 --- a/package.json +++ b/package.json @@ -1,54 +1,53 @@ { "name": "docsy", - "version": "0.9.2-dev.0-unreleased", - "version.next": "0.9.3-dev.0-unreleased", + "version": "0.12.1-dev-unreleased", + "version.next": "0.12.2-dev-unreleased", "repository": "github:google/docsy", "homepage": "https://www.docsy.dev", "license": "Apache-2.0", "scripts": { "_cd:docs": "cd userguide &&", - "_check:format": "npx prettier --check .??* *.md", + "_check:format": "npx prettier --check *.md", + "_commit:public": "npm run cd:docs -- _commit:public", "_cp:bs-rfs": "npx cpy 'node_modules/bootstrap/scss/vendor/*' assets/_vendor/bootstrap/scss/", "_diff:check": "git diff --name-only --exit-code", - "_mkdir:hugo-mod": "npx mkdirp ../github.com/FortAwesome/Font-Awesome ../github.com/twbs/bootstrap", - "_prebuild": "npm run _cp:bs-rfs", - "_test:docs": "npm run cd:docs test", - "build:preview": "npm run cd:docs build:preview", - "build:production": "npm run cd:docs build:production", - "build": "npm run cd:docs build", + "_gen-chroma-styles": "bash -c tools/gen-chroma-styles.sh && bash -c 'tools/gen-chroma-styles.sh -s onedark -o _dark.scss'", + "_mkdir:hugo-mod": "node tools/mkdirp-hugo-mod.js ..", + "_prepare": "npm run _cp:bs-rfs && npm run _gen-chroma-styles && npm run get:hugo-modules", + "build:preview": "npm run cd:docs -- build:preview --", + "build:production": "npm run cd:docs -- build:production --", + "build": "npm run cd:docs -- build --", "cd:docs": "npm run _cd:docs -- npm run", - "check": "npm run check:format && npm run check:links--md", "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", - "check:links--md": "ls *.md | xargs npx markdown-link-check --config .markdown-link-check.json", - "check:links:all": "npm run cd:docs check:links:all", + "check:links:internal": "npm run cd:docs check:links:internal", "check:links": "npm run cd:docs check:links", + "check": "npm run check:format", + "ci:post": "npm run fix:format && npm run _diff:check", + "ci:prepare": "npm run docs-install && npm run _prepare && npm run _diff:check", "docs-install": "npm run _cd:docs -- npm install", - "fix:format": "npm run _check:format -- --write", + "fix:format": "npm run _check:format -- --write && npm run cd:docs fix:format", "get:hugo-modules": "node tools/getHugoModules/index.mjs", "postinstall": "npm run _mkdir:hugo-mod", - "prebuild:preview": "npm run _prebuild", - "prebuild:production": "npm run _prebuild", - "preserve": "npm run _prebuild", - "pretest": "npm run _prebuild", "serve": "npm run cd:docs serve", - "test:all": "npm run _test:docs && npm run check && npm run fix:format && npm run _diff:check", - "test": "npm run _test:docs", - "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest", - "update:pkg:hugo": "npm install --save-exact -D hugo-extended@latest" + "test:all": "npm run ci:prepare && npm run check && npm run cd:docs test && npm run ci:post", + "test": "npm run check && npm run cd:docs test", + "update:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest", + "update:hugo": "npm install --save-exact -D hugo-extended@latest", + "update:pkgs": "npx npm-check-updates -u && npm run cd:docs update:pkgs" }, - "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome userguide ", "dependencies": { - "@fortawesome/fontawesome-free": "6.5.2", - "bootstrap": "5.3.3" + "@fortawesome/fontawesome-free": "6.7.2", + "bootstrap": "5.3.6" }, "devDependencies": { "cpy-cli": "^5.0.0", - "hugo-extended": "0.125.2", - "markdown-link-check": "^3.11.2", - "mkdirp": "^3.0.1", - "prettier": "^3.2.5" + "hugo-extended": "0.147.5", + "netlify-cli": "^21.5.0", + "npm-check-updates": "^18.0.1", + "prettier": "^3.5.3" }, "engines": { - "node": ">=20" - } + "node": ">=22" + }, + "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome onedark twbs netlify pkgs userguide -" } diff --git a/theme.toml b/theme.toml index ee8bf6457e..161eee86f0 100644 --- a/theme.toml +++ b/theme.toml @@ -1,3 +1,4 @@ +# cSpell:ignore demosite licenselink name = "Docsy" license = "Apache 2.0" licenselink = "https://github.com/google/docsy/blob/main/LICENSE" @@ -6,7 +7,7 @@ homepage = "https://docsy.dev" demosite = "https://example.docsy.dev/" tags = ["documentation", "multilingual", "customizable", "responsive", "docs"] features = [] -min_version = "0.110.0" +min_version = "0.146.0" [author] name = "The Docsy Authors" diff --git a/tools/gen-chroma-styles.sh b/tools/gen-chroma-styles.sh new file mode 100755 index 0000000000..2a83941437 --- /dev/null +++ b/tools/gen-chroma-styles.sh @@ -0,0 +1,71 @@ +#!/bin/bash + +set -eo pipefail + +HUGO="npx hugo" +CHROMA_STYLE=tango +DEST_DIR=assets/scss/td/chroma +DEST_FILE=_light.scss +DEST_PATH=/dev/null # Set in process_CLI_args + +function _usage() { + cat <&2 + exit $status +} + +function process_CLI_args() { + while getopts ":ho:s:" opt; do + case $opt in + h) + usage + ;; + o) + DEST_FILE="$OPTARG" + ;; + s) + CHROMA_STYLE="$OPTARG" + ;; + \?) + echo "ERROR: unrecognized flag: -$OPTARG" + usage 1; + ;; + esac + done + + shift $((OPTIND-1)) + if [ "$#" -gt 0 ]; then + echo "ERROR: extra argument(s): $*" >&2 + usage 1; + fi + + DEST_PATH="$DEST_DIR/$DEST_FILE" +} + +function main() { + process_CLI_args "$@" + + # For more options, see https://gohugo.io/commands/hugo_gen_chromastyles/ + local cmd="$HUGO gen chromastyles --style=$CHROMA_STYLE >> $DEST_PATH" + echo "Generating $DEST_FILE using: $cmd" + + echo "/* Chroma style: $CHROMA_STYLE */" > $DEST_PATH + eval "$cmd" +} + +main "$@" diff --git a/tools/getHugoModules/index.mjs b/tools/getHugoModules/index.mjs index 33312e8fb9..861f6a17dc 100644 --- a/tools/getHugoModules/index.mjs +++ b/tools/getHugoModules/index.mjs @@ -21,7 +21,7 @@ function getHugoModule(npmPkgNm, hugoModuleRefAtV) { throw new Error(msg); } - const command = `hugo mod get ${hugoModuleRefAtV}${pkgVers}`; + const command = `npx hugo mod get ${hugoModuleRefAtV}${pkgVers}`; console.log(`> ${command}`); const output = execSync(command); console.log(output.toString()); diff --git a/tools/install-hugo.sh b/tools/install-hugo.sh index 9544797a13..4bd74fb19d 100755 --- a/tools/install-hugo.sh +++ b/tools/install-hugo.sh @@ -6,7 +6,11 @@ set -e PKG_JSON=${1:-package.json} -if ! npm ls hugo-extended; then - _HUGO_EXTENDED_PKG=`perl -ne 'print "$1\@$2" if /"(hugo-extended)":\s*"\D*(.+?)"/' $PKG_JSON` - (set -x && npm install --save-exact -D $_HUGO_EXTENDED_PKG --omit=optional) +if ! npm ls hugo-extended2; then + _HUGO_EXTENDED_VERS=`perl -ne 'print "$1" if /"hugo-extended":\s*"\D*(.+?)"/' $PKG_JSON` + set -x + if ! npm install --save-exact -D hugo-extended@$_HUGO_EXTENDED_VERS --omit=optional; then + echo "Trying fork instead:" + npm install --save-exact -D chalin/hugo-extended#v$_HUGO_EXTENDED_VERS --omit=optional + fi fi diff --git a/tools/mkdirp-hugo-mod.js b/tools/mkdirp-hugo-mod.js new file mode 100644 index 0000000000..ca50269198 --- /dev/null +++ b/tools/mkdirp-hugo-mod.js @@ -0,0 +1,59 @@ +// Helper script to create empty Hugo-module directories for Docsy dependencies +// listed in `go.mod`. This is necessary for projects not using Hugo modules. For +// details, see +// https://www.docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect + +const fs = require('fs'); +const path = require('path'); + +if (process.env.DOCSY_MKDIR_HUGO_MOD_SKIP) { + console.log("DOCSY_MKDIR_HUGO_MOD_SKIP is set. Skipping directory creation."); + process.exit(0); +} + +const modulePathPrefix = process.argv[2] || '..'; +console.log( + `Creating empty directories under MODULE_PATH_PREFIX: ${modulePathPrefix} + which resolves to: ${path.resolve(modulePathPrefix)}\n` +); + +// Extract module paths from `go.mod`, assuming the dependencies appear in the form: +// +// require ( +// github.com/... +// ... +// ) +function extractModulePaths() { + const goModPath = path.join(__dirname, '..', 'go.mod'); + + let directories = []; + try { + const goModContent = fs.readFileSync(goModPath, 'utf8'); + const lines = goModContent.split('\n'); + lines.forEach((line) => { + line = line.trim(); + if (!line.startsWith('github.com')) return; + const modulePath = line.split(' ')[0]; + directories.push(modulePath); + }); + } catch (error) { + console.error(`Error reading go.mod file: ${error.message}`); + process.exit(1); + } + return directories; +} + +function createDirectory(targetPath) { + if (!fs.existsSync(targetPath)) { + console.log(`+ Creating directory ${targetPath}`); + fs.mkdirSync(targetPath, { recursive: true }); + } else { + console.log(`> Directory already exists: ${targetPath}`); + } +} + +const directories = extractModulePaths(); +directories.forEach((dir) => { + const targetPath = path.join(modulePathPrefix, dir); + createDirectory(targetPath); +}); diff --git a/tools/prettier-ignore-helper.pl b/tools/prettier-ignore-helper.pl new file mode 100755 index 0000000000..51a8958b51 --- /dev/null +++ b/tools/prettier-ignore-helper.pl @@ -0,0 +1,75 @@ +#!/usr/bin/env perl +use strict; +use warnings; + +# Usage: perl add_prettier_ignore.pl file1.md [file2.md ...] + +foreach my $file (@ARGV) { + open my $in, '<', $file or die "Cannot open $file: $!"; + my @lines = <$in>; + close $in; + + open my $out, '>', $file or die "Cannot write to $file: $!"; + + my $inside_ignore = 0; + my $i = 0; + while ($i <= $#lines) { + my $line = $lines[$i]; + + # Detect entering or leaving prettier-ignore regions + if ($line =~ //) { + $inside_ignore = 1; + print $out $line; + $i++; + next; + } + if ($line =~ //) { + $inside_ignore = 0; + print $out $line; + $i++; + next; + } + + # Detect non-indented tabpane opening + if (!$inside_ignore && $line =~ /^\s*\{\{<\s*tabpane.*?>\}\}\s*$/ && $line !~ /^\s{1,}\{\{<\s*tabpane.*?>\}\}\s*$/) { + # Only process if NOT indented (no leading spaces/tabs) + if ($i == 0 || $lines[$i-1] !~ //) { + print $out "\n"; + } + print $out $line; + $i++; + # Print inner block until non-indented closing shortcode + while ($i <= $#lines) { + my $inner = $lines[$i]; + print $out $inner; + if ($inner =~ /^\s*\{\{<\s*\/tabpane\s*>\}\}\s*$/ && $inner !~ /^\s{1,}\{\{<\s*\/tabpane\s*>\}\}\s*$/) { + # Check next line for ignore-end + if ($i == $#lines || $lines[$i+1] !~ //) { + print $out "\n"; + } + $i++; + last; + } + $i++; + } + next; + } + + # Detect indented tabpane opening/closing not in an ignore region and warn + if (!$inside_ignore && + ( + ($line =~ /^\s+\{\{<\s*tabpane.*?>\}\}\s*$/) || + ($line =~ /^\s+\{\{<\s*\/tabpane.*?>\}\}\s*$/) + ) + ) { + print STDERR "$file:", $i+1, ": WARNING: Indented tabpane shortcode found, usually because it is in a list. Add prettier-ignore directive manually before the start of the list.\n"; + } + + print $out $line; + $i++; + } + + close $out; +} + +print "Processed ", scalar(@ARGV), " files.\n"; diff --git a/userguide/.htmltest.yml b/userguide/.htmltest.yml index 68c98992f0..5dc75859df 100644 --- a/userguide/.htmltest.yml +++ b/userguide/.htmltest.yml @@ -1,10 +1,26 @@ +# cSpell:ignore github regexs +CacheExpires: 9000h # ~ 12 months DirectoryPath: public CheckDoctype: false # Sadly, this is false only because of `static/google*.html` IgnoreAltMissing: true # FIXME IgnoreDirectoryMissingTrailingSlash: true # FIXME -IgnoreDirs: [_print] # FIXME +TestFilesConcurrently: true +IgnoreDirs: + - _print + - ^blog/(\d+/)?page/\d+ IgnoreEmptyHref: true # FIXME IgnoreInternalEmptyHash: true # FIXME IgnoreInternalURLs: # list of paths IgnoreURLs: # list of regexs of paths or URLs to be ignored + - \?no-link-check + - (index.xml|_print/)$ # ignore + - ^https?://[^/]+/(categories|tags)/ # ignore Docsy-generated content + - ^https?://localhost\b + # Ignore Docsy-generated GitHub links for now + - ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc - ^https://twitter.com/docsydocs$ + # Too flaky or unnecessary + - ^https://badges.netlify.com/api + - ^https://code.jquery.com + # TEMPORARY until we're done with https://github.com/google/docsy/issues/2243 + # - ^https://github.com/google/docsy/blob/main/layouts/.*_td-content-after-header.html$ diff --git a/userguide/.prettierignore b/userguide/.prettierignore new file mode 100644 index 0000000000..469dd1b49c --- /dev/null +++ b/userguide/.prettierignore @@ -0,0 +1,14 @@ +# cSpell:ignore lookandfeel + +.* +/* +!/content +/content/* +!/content/en +/content/en/* + +!/content/en/docs +/content/en/docs/* +!/content/en/docs/_index.md +!/content/en/docs/adding-content +!/static diff --git a/userguide/Makefile b/userguide/Makefile index 7a4aa11f55..cf08b71f39 100644 --- a/userguide/Makefile +++ b/userguide/Makefile @@ -1,6 +1,11 @@ +# Set REFCACHE to another value to disable htmltest refcache-file manipulation +REFCACHE?=refcache HTMLTEST_DIR=tmp HTMLTEST?=htmltest # Specify as make arg if different -HTMLTEST_ARGS?=--skip-external +HTMLTEST_ARGS?=--log-level 1 +LINK_CACHE_FILE?=refcache.json +LINK_CACHE_FILE_DEST_DIR?=static +LINK_CACHE_FILE_SRC_DIR?=$(HTMLTEST_DIR)/.htmltest # Use $(HTMLTEST) in PATH, if available; otherwise, we'll get a copy ifeq (, $(shell which $(HTMLTEST))) @@ -10,7 +15,36 @@ GET_LINK_CHECKER_IF_NEEDED=get-link-checker endif endif -check-links: $(GET_LINK_CHECKER_IF_NEEDED) +default: + @echo "Make what? Target list:\n" + @make -rpn | grep '^[a-z]\S*:' | sed 's/://' | sort + +$(LINK_CACHE_FILE_SRC_DIR): + mkdir -p $(LINK_CACHE_FILE_SRC_DIR) + +$(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE): + mkdir -p $(LINK_CACHE_FILE_DEST_DIR) + echo '{}' > $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) + +refcache-restore: $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR) +ifeq (refcache, $(REFCACHE)) + cp $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)/ +else + @echo "SKIPPING refcache-restore" +endif + +refcache-save: +ifeq (refcache, $(REFCACHE)) + cp $(LINK_CACHE_FILE_SRC_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_DEST_DIR)/ + npx prettier --prose-wrap=always --write $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) +else + @echo "SKIPPING refcache-save" +endif + +check-links: $(GET_LINK_CHECKER_IF_NEEDED) \ + refcache-restore check-links-only refcache-save + +check-links-only: $(HTMLTEST) $(HTMLTEST_ARGS) clean: diff --git a/userguide/assets/scss/_styles_project.scss b/userguide/assets/scss/_styles_project.scss index e69de29bb2..cf04905804 100644 --- a/userguide/assets/scss/_styles_project.scss +++ b/userguide/assets/scss/_styles_project.scss @@ -0,0 +1 @@ +@import 'td/code-dark'; diff --git a/userguide/content/en/_index.md b/userguide/content/en/_index.md index b613e3f0f3..1f667e86c8 100644 --- a/userguide/content/en/_index.md +++ b/userguide/content/en/_index.md @@ -20,7 +20,7 @@ for technical documentation sets. Our aim is to help you get a working documentation site up and running as easily as possible, so you can concentrate on creating great content for your users. - + Deploys by Netlify {{% /blocks/lead %}} diff --git a/userguide/content/en/blog/2023/bootstrap-5-migration.md b/userguide/content/en/blog/2023/bootstrap-5-migration.md index 8975021134..250d199f63 100644 --- a/userguide/content/en/blog/2023/bootstrap-5-migration.md +++ b/userguide/content/en/blog/2023/bootstrap-5-migration.md @@ -67,7 +67,7 @@ For details and an example, see: - [Sass](https://getbootstrap.com/docs/5.2/migration/#sass) section of the migration page -- [\[BSv5\] Adjust `media-breakpoint-down()` argument · Docsy PR #1367](https://github.com/google/docsy/pull/1367) +- [[BSv5] Adjust `media-breakpoint-down()` argument · Docsy PR #1367](https://github.com/google/docsy/pull/1367) ### Grid `.row` and `.col` style changes are breaking @@ -111,11 +111,11 @@ updates and might impact Docsy-based projects as well: References: -- [\[BSv5\] Row/col formatting breaks Docsy components #1466](https://github.com/google/docsy/issues/1466), +- [[BSv5] Row/col formatting breaks Docsy components #1466](https://github.com/google/docsy/issues/1466), in particular - - [\[BSv5\] Footer fixes: reset flex-shrink, and more·](https://github.com/google/docsy/pull/1373) + - [[BSv5] Footer fixes: reset flex-shrink, and more·](https://github.com/google/docsy/pull/1373) [Docsy PR](https://github.com/google/docsy/pull/1367)[ #1373](https://github.com/google/docsy/pull/1373) - - [\[BSv5\] Footer: drop flex-shrink tweak + other adjustments ·](https://github.com/google/docsy/pull/1523) + - [[BSv5] Footer: drop flex-shrink tweak + other adjustments ·](https://github.com/google/docsy/pull/1523) [Docsy PR](https://github.com/google/docsy/pull/1367)[ #1523](https://github.com/google/docsy/pull/1523) - [Why are all col classes 'position: relative'? · Bootstrap v4 issue #25254](https://github.com/twbs/bootstrap/issues/25254) - [Why flex-shrink 0 for all columns? · Bootstrap discussion #37951](https://github.com/orgs/twbs/discussions/37951) @@ -165,7 +165,7 @@ imports from References: -- [\[BSv5\] Fix SCSS functions import issue ... ·](https://github.com/google/docsy/pull/1388) +- [[BSv5] Fix SCSS functions import issue ... ·](https://github.com/google/docsy/pull/1388) [Docsy PR](https://github.com/google/docsy/pull/1367) [#1388](https://github.com/google/docsy/pull/1388) - [New \_maps.scss](https://getbootstrap.com/docs/5.2/migration/#new-_mapsscss) @@ -227,7 +227,7 @@ Docsy house cleaning. For details concerning both breaking and non-breaking Docsy-specific changes, consult the [changelog](https://github.com/google/docsy/blob/main/CHANGELOG.md#070). In particular, one non-breaking but important change to be aware of is: -[\[BSv5\] Docsy variables cleanup ... PR #1462](https://github.com/google/docsy/pull/1462). +[[BSv5] Docsy variables cleanup ... PR #1462](https://github.com/google/docsy/pull/1462). ## Give it a try! diff --git a/userguide/content/en/blog/2024/0.10.0.md b/userguide/content/en/blog/2024/0.10.0.md new file mode 100644 index 0000000000..7aa0c098e0 --- /dev/null +++ b/userguide/content/en/blog/2024/0.10.0.md @@ -0,0 +1,108 @@ +--- +title: Docsy 0.10.0 release report +linkTitle: Release 0.10.0 +author: > + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), + for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc) +date: 2024-05-01 +# prettier-ignore +cSpell:ignore: CNCF Chalin subdir deprecat upvoted pageinfo lookandfeel lightdark +--- + +The big news with Docsy [0.10.0] is color themes and dark mode! + +## Hugo: breaking changes and deprecation notices + +In this release, Docsy's Hugo dependency is upgraded to **0.125.4** from +0.122.0. An important thing to note here is that Hugo [0.123.0] was a +significant upgrade that included some **breaking changes**. Before upgrading to +this Docsy version, review Hugo's deprecation notices and breaking changes since +0.122.0. + +[0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 + +{{% alert title="Hugo version support reminder" color="primary" %}} + +Each Docsy version officially **only** supports the Hugo version specified in +the project's [package.json] entry for [hugo-extended]. Any other compatibility +is on a best effort basis. + +[hugo-extended]: https://github.com/jakejarvis/hugo-extended +[package.json]: https://github.com/google/docsy/blob/main/package.json + +{{% /alert %}} + +A number of updates to this release were to address Hugo's deprecation notices. +For the complete list, search for [0.10.0] release changes with "deprecat" in +the title. + +## Color themes and dark-mode support + +The main feature of this release is the [Upgrade to Bootstrap 5.3 +(#1528)][#1528] from 5.2. This minor Bootstrap release introduces support [color +modes], also called color themes. + +As a validation of this upgrade, Docsy has been enhanced to support [dark mode], +the _most upvoted_ Docsy enhancement request ([#331]) prior to this release. + +To learn how to enable a **light/dark mode dropdown menu** for your project, see +[Light/dark mode menu]. We have enabled this menu for the Docsy [User Guide], so +if you're reading this post online, give dark mode a try! + +[#331]: https://github.com/google/docsy/issues/331 +[#1528]: https://github.com/google/docsy/issues/1528 +[color modes]: https://getbootstrap.com/docs/5.3/customize/color-modes/ +[dark mode]: https://getbootstrap.com/docs/5.3/customize/color-modes/#dark-mode +[Light/dark mode menu]: /docs/adding-content/lookandfeel/#lightdark-mode-menu +[User Guide]: http://localhost:1313/docs/ + +{{% alert title="Important style changes" %}} + +The styling of the following shortcodes and page elements have been adjusted to +ensure that they are compatible with light and dark modes. + +You'll needs to **revisit your styles if you customized the SCSS** associated +with these shortcodes and elements. + +- [`alert`] ([#1908]) +- [`card`] ([#1922]) +- [`pageinfo`] ([#1915]) +- [Tabbed-pane] shortcodes ([#1920]) + +The [search box styling][#1896] as well as the [doc-page left-nav][#1908] have +had their styles adjusted as well. + +[#1896]: https://github.com/google/docsy/pull/1896 +[#1908]: https://github.com/google/docsy/pull/1908 +[#1915]: https://github.com/google/docsy/pull/1915 +[#1920]: https://github.com/google/docsy/pull/1920 +[#1922]: https://github.com/google/docsy/pull/1922 +[`alert`]: /docs/adding-content/shortcodes/#alert +[`card`]: /docs/adding-content/shortcodes/#shortcode-card-programming-code +[`pageinfo`]: /docs/adding-content/shortcodes/#pageinfo +[tabbed-pane]: /docs/adding-content/shortcodes/#tabbed-panes + +{{% /alert %}} + +## Release details + +For the complete list of changes in this release, including updates to +FontAwesome, Mermaid, Algolia, and KaTex, see the [0.10.0] release entry and +issue +[Release 0.10.0 preparation (#1759)](https://github.com/google/docsy/issues/1759). + +## What's next? + +Which Docsy improvements are on the horizon? For work items _tentatively_ +planned for the next release, see +[Release 0.11.0 preparation (#1944)](https://github.com/google/docsy/issues/1944). + +{{% alert title="Vote" color="primary" %}} + +If you'd like a feature or fix to be considered for inclusion in an upcoming +release, remember to upvote (with a thumbs up) the associated issue or PR. + +{{% /alert %}} + +[CL@0.10.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#0100 +[0.10.0]: https://github.com/google/docsy/releases/tag/v0.10.0 diff --git a/userguide/content/en/blog/2024/0.9.0.md b/userguide/content/en/blog/2024/0.9.0.md index a4da0fd986..ad044d4840 100644 --- a/userguide/content/en/blog/2024/0.9.0.md +++ b/userguide/content/en/blog/2024/0.9.0.md @@ -3,11 +3,11 @@ title: Docsy 0.9.0 release report linkTitle: Release 0.9.0 author: > [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), - for the [Docsy Steering - Committee](/blog/2022/hello/#introducing-the-psc) + for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc) date: 2024-02-09 +updated: 2024-12-12 # prettier-ignore -cSpell:ignore: CNCF Chalin subdir +cSpell:ignore: CNCF Chalin subdir sarahmaddox jmooring --- Docsy [0.9.0] is a sizable[^1] release ([containing 65+ PRs][v0.8.0...v0.9.0]) @@ -17,6 +17,7 @@ related to: - [Footer improvements](#footer) - [Repository links and other page info](#page-meta) - [Look and feel](#look-and-feel) +- [Continuous integration testing](#ci) Thank you to all [contributors][0.9.0]! @@ -41,7 +42,7 @@ subpart of center ([#1817]). Each part has its own class, such as This release has resolves **_the_ longest standing and first ever issue created** in Docsy! -- [The footer should allow a more flexible copyright statement #2][#2] by +- [The footer should allow a more flexible copyright statement (#2)][#2] by [@sarahmaddox] The footer copyright now supports a date-range and the site-copyright as a @@ -64,8 +65,8 @@ fallback: `.params.ui.footer_about_enable` to true in your project's configuration file. Parameter `.params.ui.footer_about_disable` is deprecated. - The All-rights-reserved text is hidden by default. To make it visible, add the - following to your `_styles_project.scss` [project style file] (optionally - with a `!important` modifier — not shown): + following to your `_styles_project.scss` [project style file] (optionally with + a `!important` modifier — not shown): ```scss .td-footer__all_rights_reserved { display: inline; @@ -89,7 +90,7 @@ Half-jokingly, Lisa commented: _All we needed was several years and a few Hugo improvements_. That is, it wasn't until [Hugo 0.112.0], released in May 2023, that the necessary [functions] became available. For details, see: -- [Fix links for single language sites #1744][#1744] +- [Fix links for single language sites (#1744)][#1744] - [Hugo v0.112.0 - New template functions][tmpl-func], by [@jmooring] We're convinced that Lisa's fix has squashed repo-link bugs for good! @@ -99,7 +100,7 @@ sites that use mounts and that have pages configured with [path_base_for_github_subdir]. As can be seen from [Repository / page-meta link fixes and improvements -#1841][#1841], several issues remain, but resolving [#1744] establishes the +(#1841)][#1841], several issues remain, but resolving [#1744] establishes the necessary foundation for future work. The issues listed in [#1841] will be addressed in a future release through further layout refactoring and extension. @@ -144,22 +145,46 @@ The [blocks/feature] shortcode no longer includes ellipsis ("...") after the "Read more" link text. Projects wanting to recover the ellipsis can add it to the `"ui_read_more"` [language parameter] for your site's languages ([#1820]). +## Continuous integration testing {#ci} + +To ensure the quality and stability of Docsy, this release introduces a highly +anticipated developer feature: **continuous integration (CI) testing** support +through GitHub Actions. + +Each PR and main-branch commit triggers ([workflows]): + +- Cross-platform tests on Linux and Windows. +- Build tests to ensure that Docsy and its User Guide build successfully and + pass checks, such as link validation. +- Smoke tests that build a Docsy site from scratch. These tests validate Docsy's + use as both a Hugo module and an NPM module. + +While Windows support is maintained on a best-effort basis due to limited access +to Windows environments, running cross-platform tests helps identify potential +build issues sooner. + +This initiative is an important step forward in ensuring the reliability of the +theme. We plan to [expand test coverage (#726)][#726] in the future. + +[#726]: https://github.com/google/docsy/issues/726 +[workflows]: https://github.com/google/docsy/blob/main/.github/workflows + ## References and future releases For the complete list of changes in this release, see the [0.9.0] release entry and issue -[Release 0.9.0 preparation #1759](https://github.com/google/docsy/issues/1759). +[Release 0.9.0 preparation (#1759)](https://github.com/google/docsy/issues/1759). Which Docsy improvements are on the horizon? For work items _tentatively_ planed for the next release, see -[Release 0.10.0 preparation #1812](https://github.com/google/docsy/issues/1812). +[Release 0.10.0 preparation (#1812)](https://github.com/google/docsy/issues/1812). Feature and fix candidates for 0.10.0 and beyond currently include more Bootstrap work, in preparation for the reintroduction of RTL support — specifically: - [BSv5.2 upgrade followup](https://github.com/google/docsy/issues/1510) -- [Upgrade to Bootstrap 5.3 #1528](https://github.com/google/docsy/issues/1528) +- [Upgrade to Bootstrap 5.3 (#1528)](https://github.com/google/docsy/issues/1528) - [[BSv5] Reintroduce RTL support using RTLCSS bootstrap](https://github.com/google/docsy/issues/1442) - [Support adding theme colors](https://github.com/google/docsy/issues/1845) diff --git a/userguide/content/en/blog/2024/year-in-review.md b/userguide/content/en/blog/2024/year-in-review.md new file mode 100644 index 0000000000..6579025165 --- /dev/null +++ b/userguide/content/en/blog/2024/year-in-review.md @@ -0,0 +1,169 @@ +--- +title: 'Docsy 2024 Review: Adoptions and Enhancements' +linkTitle: '2024 Review: Adoptions and Enhancements' +date: 2024-12-12 +author: >- + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), + for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc) +description: >- + Celebrating Docsy's 2024 growth in features and adoption, including a 57% + usage increase, new features like dark mode, and improved internationalization + support. +# prettier-ignore +cSpell:ignore: Chalin jaegertracing mentees opentelemetry toto upvoted kubernetes theupdateframework Dindi Dariksha Ansari +--- + +As we reflect on 2024, it’s exciting to see steady progress toward the goals +outlined in our [2024 priorities]. This year, we focused on enhancing stability, +improving internationalization, and delivering long-anticipated features like +dark mode and continuous integration (CI) testing. + +> Docsy’s use **increased by 57%** in +> 2024, from 1.4K to 2.2K projects! [^1] + +Let’s dive into the development highlights from 2024 and take a peek at what +lies ahead. + +[2024 priorities]: ../2023/priorities-for-2024/ +[GitHub dependents data]: https://github.com/google/docsy/network/dependents + +## Release highlights + +We published three releases this year, each focusing on stability while +introducing at least one major feature enhancement. Highlights include: + +- **[0.9.0](https://www.docsy.dev/blog/2024/0.9.0/)** added _long-awaited_: + - **CI testing** via GitHub Actions to ensure quality and reliability across + Linux and Windows. + - **Footer customization** — Docsy's [longest-standing issue (#2)][#2]! + — as well as improved repository links, and enhanced accessibility and + look-and-feel. +- **[0.10.0](https://www.docsy.dev/blog/2024/0.10.0/):** + - Enabled [color themes and **dark mode**][dark mode] via Bootstrap 5.3 + upgrade, marking the completion of the [Bootstrap 5 migration] started + in 2021. Also made adjustments to shortcodes and styles for dark-mode + compatibility. + - Addressed breaking changes resulting from the major core upgrade to Hugo + 0.123.0. +- **[0.11.0](https://github.com/google/docsy/releases/tag/v0.11.0):** + - Enhanced internationalization by reintroducing **Right-To-Left (RTL) + language support** using Bootstrap's RTL capabilities. + +[#2]: https://github.com/google/docsy/issues/2 +[Bootstrap 5 migration]: https://github.com/google/docsy/issues/470 + +## Major feature enhancements {#enhancements} + +In addition to CI testing, a key development feature contributing to Docsy's +stability, here are the major user-facing enhancements introduced in 2024. + +### Dark mode support + +[Dark mode] support was the **_most upvoted_ Docsy enhancement** prior to its +debut in v0.10.0. Powered by Bootstrap 5.3 color themes, this Docsy feature +includes a built-in light/dark mode menu selector for easy implementation. + +We plan on [enabling dark mode] in the [Docsy example], for even easier +adoption. Dark mode has already been adopted in notable projects like +OpenTelemetry ([opentelemetry.io#4023]). + +[enabling dark mode]: https://github.com/google/docsy-example/issues/285 +[Docsy example]: https://github.com/google/docsy-example +[opentelemetry.io#4023]: + https://github.com/open-telemetry/opentelemetry.io/issues/4023 + +### Right-To-Left (RTL) language support + +[RTL language support (#1933)][#1933], reintroduced through Bootstrap's use of +the mature and well-vetted [RTLCSS] framework, replaced Docsy's deprecated +custom RTL solution from 2023. + +This enhancement meets longstanding multilingual documentation needs. Notably, +RTL support has been requested by major Docsy-based sites, including the two +2024 [top-velocity projects] of the [CNCF]: + +- [Kubernetes]: + [right-to-left language support #22730](https://github.com/kubernetes/website/issues/22730) + - [Localize website into Arabic (ar) #22726](https://github.com/kubernetes/website/issues/22726) + - [Localize website into Persian (fa) #22727](https://github.com/kubernetes/website/issues/22727) +- [OpenTelemetry]: + - [Add Persian version of website pages #4990](https://github.com/open-telemetry/opentelemetry.io/issues/4990) + +[#1933]: https://github.com/google/docsy/pull/1933 +[CNCF]: https://www.cncf.io +[dark mode]: 0.10.0/#color-themes-and-dark-mode-support +[Kubernetes]: https://kubernetes.io +[OpenTelemetry]: https://opentelemetry.io +[top-velocity projects]: + https://www.cncf.io/blog/2024/07/11/as-we-reach-mid-year-2024-a-look-at-cncf-linux-foundation-and-top-30-open-source-project-velocity/ +[RTLCSS]: https://rtlcss.com/ + +## Adoptions and the Docsy Starter + +One of the most exciting developments in 2024 has been Docsy's growing adoption. +GitHub analytics show a **57% increase in usage**, reaching **2.2K projects** as +of this writing. + +Adoption among CNCF projects has also grown since our [2023 report]. This year, +[Linux Foundation mentees][LFX] [Sandra Dindi] and [Dariksha Ansari] used the [CNCF Docsy starter] to migrate the +following sites to Docsy: + +- **[The Update Framework](https://theupdateframework.io)** + ([theupdateframework.io#105]) +- **[in-toto](https://in-toto.io)** ([in-toto.io#76]) + +Additionally, the [Kubernetes website] is undergoing a significant Docsy upgrade +from v0.2, to align with the latest version and reduce technical debt: + +- [Align with upstream Docsy kubernetes.io#41171](https://github.com/kubernetes/website/issues/41171) +- [Update Docsy step by step to the latest Docsy kubernetes.io#44002](https://github.com/kubernetes/website/issues/44002) + +The upgrade is progressing well, as shown in the ongoing efforts documented in +the [0.3.x upgrade] and [0.5.x upgrade]. + +[0.3.x upgrade]: https://github.com/kubernetes/website/pull/48721 +[0.5.x upgrade]: https://github.com/kubernetes/website/issues/48807 +[theupdateframework.io#105]: + https://github.com/theupdateframework/theupdateframework.io/pull/105 +[CNCF Docsy starter]: https://github.com/chalin/docsy-starter +[LFX]: + https://www.cncf.io/blog/2024/09/27/congratulations-to-45-cncf-term-1-2024-lfx-program-mentees/ +[2023 report]: + https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/ +[in-toto.io#76]: https://github.com/in-toto/in-toto.io/issues/76 +[Kubernetes website]: https://github.com/kubernetes/website +[Dariksha Ansari]: https://mentorship.lfx.linuxfoundation.org/project/34314eb1-0fc3-4802-ab04-2265418c2e48 +[Sandra Dindi]: https://mentorship.lfx.linuxfoundation.org/project/e35f28f9-f333-47a8-a76a-119567cf10ca + +## What's ahead? + +Looking ahead, we’re excited to continue supporting the Docsy upgrade and +adoption efforts by projects such as [gRPC (grpc.io#1389)] and [Jaeger +(jaegertracing#746)]. + +For features tentatively planned for the first release of 2025, see [Release +0.12.0 preparation #2108]. The most upvoted enhancement requests are currently: +[^2] + +- [Navigation indication on the right TOC #349](https://github.com/google/docsy/issues/349) +- [Repository / page-meta link fixes and improvements #1841](https://github.com/google/docsy/issues/1841), + particularly for [GitLab](https://github.com/google/docsy/issues/375) +- [Drop jQuery #1436](https://github.com/google/docsy/issues/1436) + +Thank you to all contributors and users who made 2024 a meaningful year for +Docsy. Wishing you a fantastic end to 2024 and a great start to 2025! Let’s +continue creating exceptional documentation together. + +[^1]: Based on GitHub analytics [Docsy dependents] as of the time of writing. + +[^2]: + Remember to + [vote for your most-desired feature](https://github.com/google/docsy/issues). + +[Docsy dependents]: https://github.com/google/docsy/network/dependents +[cncf-top]: + https://www.cncf.io/blog/2024/07/11/as-we-reach-mid-year-2024-a-look-at-cncf-linux-foundation-and-top-30-open-source-project-velocity/ +[gRPC (grpc.io#1389)]: https://github.com/grpc/grpc.io/issues/1389 +[Jaeger (jaegertracing#746)]: + https://github.com/jaegertracing/documentation/issues/746 +[Release 0.12.0 preparation #2108]: https://github.com/google/docsy/issues/2108 diff --git a/userguide/content/en/docs/_index.md b/userguide/content/en/docs/_index.md index 77b28412c8..1b4b11fc00 100755 --- a/userguide/content/en/docs/_index.md +++ b/userguide/content/en/docs/_index.md @@ -1,43 +1,78 @@ - --- title: Welcome to Docsy linkTitle: Documentation -menu: {main: {weight: 20}} +menu: { main: { weight: 20 } } --- -Welcome to the Docsy theme user guide! This guide shows you how to get started creating technical documentation sites using Docsy, including site customization and how to use Docsy's blocks and templates. +Welcome to the Docsy theme user guide! This guide shows you how to get started +creating technical documentation sites using Docsy, including site customization +and how to use Docsy's blocks and templates. ## What is Docsy? -Docsy is a theme for the [Hugo](https://gohugo.io/) static site generator that's specifically designed for technical -documentation sets and has a lot of best practices built in. Use Docsy to get a working and reliable documentation -site up and running fast, and then get back to focusing on great content for your users. -[Learn more about Docsy](/about). - -In addition to the theme itself, we provide an [example site](https://github.com/google/docsy-example) that uses lots of Docsy features and has a useful skeleton site structure (with advice for what to put in it!) for a large technical documentation set. You can copy the entire site and edit it for your own projects, or just explore the site and its source to see what Docsy can do. The site you're currently reading also uses Docsy and is a useful example of a smaller Docsy docset: feel free to copy it or borrow from it if it suits your needs better than the "big" example. +Docsy is a theme for the [Hugo](https://gohugo.io/) static site generator that's +specifically designed for technical documentation sets and has a lot of best +practices built in. Use Docsy to get a working and reliable documentation site +up and running fast, and then get back to focusing on great content for your +users. [Learn more about Docsy](/about). + +In addition to the theme itself, we provide an +[example site](https://github.com/google/docsy-example) that uses lots of Docsy +features and has a useful skeleton site structure (with advice for what to put +in it!) for a large technical documentation set. You can copy the entire site +and edit it for your own projects, or just explore the site and its source to +see what Docsy can do. The site you're currently reading also uses Docsy and is +a useful example of a smaller Docsy docset: feel free to copy it or borrow from +it if it suits your needs better than the "big" example. Docsy itself does **not** provide: -* **Source hosting and management**: Our theme and site source files live on [GitHub](https://github.com/), which is the simplest approach for most projects. However, you can also keep your project files in [GitLab](https://about.gitlab.com/), [BitBucket](https://bitbucket.org/product), locally, or wherever you like. Be aware that where your source files live may affect the Docsy features you can use (such as letting users file documentation issues) and site deployment options. -* **Site deployment**: You can find out about deployment options in [Previews and Deployment](/docs/deployment/). This site uses [Netlify](https://www.netlify.com/). - -Docsy also doesn't actually generate your site's HTML files: that's Hugo's job! Hugo takes your Markdown or HTML doc source files and Docsy's theme files and builds them into a static site for deployment. You can find out more about Hugo and how it works in the [Hugo documentation](https://gohugo.io/documentation/). +- **Source hosting and management**: Our theme and site source files live on + [GitHub](https://github.com/), which is the simplest approach for most + projects. However, you can also keep your project files in + [GitLab](https://about.gitlab.com/), + [BitBucket](https://bitbucket.org/product), locally, or wherever you like. Be + aware that where your source files live may affect the Docsy features you can + use (such as letting users file documentation issues) and site deployment + options. +- **Site deployment**: You can find out about deployment options in + [Previews and Deployment](/docs/deployment/). This site uses + [Netlify](https://www.netlify.com/). + +Docsy also doesn't actually generate your site's HTML files: that's Hugo's job! +Hugo takes your Markdown or HTML doc source files and Docsy's theme files and +builds them into a static site for deployment. You can find out more about Hugo +and how it works in the [Hugo documentation](https://gohugo.io/documentation/). ## Is Docsy for me? -Docsy is particularly useful for medium to large technical documentation sets with 20+ pages of docs and/or multiple types of docs and pages: tutorials, reference documentation, blog posts, community pages, and so on. +Docsy is particularly useful for medium to large technical documentation sets +with 20+ pages of docs and/or multiple types of docs and pages: tutorials, +reference documentation, blog posts, community pages, and so on. -If you have a smaller project with only a couple of pages of documentation and hence simpler navigation needs, Docsy may be too heavyweight a solution for you. Instead, consider: +If you have a smaller project with only a couple of pages of documentation and +hence simpler navigation needs, Docsy may be too heavyweight a solution for you. +Instead, consider: -* A simpler Hugo or Jekyll theme: find out what's available in GitHub Pages' [built-in Jekyll options](https://pages.github.com/themes/) and the [Hugo theme gallery](https://themes.gohugo.io/). -* A good README file that tells users what your project does and links to some examples. +- A simpler Hugo or Jekyll theme: find out what's available in GitHub Pages' + [built-in Jekyll options](https://pages.github.com/themes/) and the + [Hugo theme gallery](https://themes.gohugo.io/). +- A good README file that tells users what your project does and links to some + examples. -If you have a very large documentation project, our example site structure may not be sufficient either, though you can still use our theme, possibly with heavier customization. +If you have a very large documentation project, our example site structure may +not be sufficient either, though you can still use our theme, possibly with +heavier customization. -If you'd like to use Docsy's layouts but prefer to use Jekyll, [vsoch](https://github.com/vsoch) has created a [Docsy Jekyll port](https://github.com/vsoch/docsy-jekyll) that includes many of Docsy's features (though as this is a separate project it won't be automatically updated along with Docsy). +If you'd like to use Docsy's layouts but prefer to use Jekyll, +[vsoch](https://github.com/vsoch) has created a +[Docsy Jekyll port](https://github.com/vsoch/docsy-jekyll) that includes many of +Docsy's features (though as this is a separate project it won't be automatically +updated along with Docsy). ## Ready to get started? -Find out how to build and serve your first site in [Get Started](/docs/get-started/). Or visit the [example site](https://example.docsy.dev) and [its repo](https://github.com/google/docsy-example) and start exploring! - - +Find out how to build and serve your first site in +[Get Started](/docs/get-started/). Or visit the +[example site](https://example.docsy.dev) and +[its repo](https://github.com/google/docsy-example) and start exploring! diff --git a/userguide/content/en/docs/adding-content/_index.md b/userguide/content/en/docs/adding-content/_index.md index 05ee953437..d0d3d4d204 100644 --- a/userguide/content/en/docs/adding-content/_index.md +++ b/userguide/content/en/docs/adding-content/_index.md @@ -1,7 +1,5 @@ --- -title: "Content and Customization" -linkTitle: "Content and Customization" +title: Content and Customization weight: 3 -description: > - How to add content to and customize your Docsy site. +description: How to add content to and customize your Docsy site. --- diff --git a/userguide/content/en/docs/adding-content/content.md b/userguide/content/en/docs/adding-content/content.md index 9c5d605050..5dc6ff8507 100644 --- a/userguide/content/en/docs/adding-content/content.md +++ b/userguide/content/en/docs/adding-content/content.md @@ -1,39 +1,81 @@ --- -title: "Adding Content" -linkTitle: "Adding Content" +title: Adding Content weight: 1 description: > Add different types of content to your Docsy site. --- -So you've got a new Hugo website with Docsy, now it's time to add some content! This page tells you how to use the theme to add and structure your site content. +So you've got a new Hugo website with Docsy, now it's time to add some content! +This page tells you how to use the theme to add and structure your site content. ## Content root directory -You add content for your site under the **content root directory** of your Hugo site project - either `content/` or a [language-specific](/docs/language/) root like `content/en/`. The main exception here is static files that you don't want built into your site: you can find out more about where you add these below in [Adding static content](#adding-static-content). The files in your content root directory are typically grouped in subdirectories corresponding to your site's sections and templates, which we'll look at in [Content sections and templates](#content-sections-and-templates). +You add content for your site under the **content root directory** of your Hugo +site project - either `content/` or a [language-specific](/docs/language/) root +like `content/en/`. The main exception here is static files that you don't want +built into your site: you can find out more about where you add these below in +[Adding static content](#adding-static-content). The files in your content root +directory are typically grouped in subdirectories corresponding to your site's +sections and templates, which we'll look at in +[Content sections and templates](#content-sections-and-templates). -You can find out more about Hugo directory structure in [Directory Structure Explained](https://gohugo.io/getting-started/directory-structure/#directory-structure-explained). +You can find out more about Hugo directory structure in +[Directory Structure Explained](https://gohugo.io/getting-started/directory-structure/#directory-structure-explained). ## Content sections and templates -Hugo builds your site pages using the content files you provide plus any templates provided by your site's theme. These templates (or *"layouts"* in Hugo terminology) include things like your page's headers, footers, navigation, and links to stylesheets: essentially, everything except your page's specific content. The templates in turn can be made up of *partials*: little reusable snippets of HTML for page elements like headers, search boxes, and more. - -Because most technical documentation sites have different sections for different types of content, the Docsy theme comes with the [following templates](https://github.com/google/docsy/tree/main/layouts) for top-level site sections that you might need: - -* [`docs`](https://github.com/google/docsy/tree/main/layouts/docs) is for pages in your site's Documentation section. -* [`blog`](https://github.com/google/docsy/tree/main/layouts/blog) is for pages in your site's Blog. -* [`community`](https://github.com/google/docsy/tree/main/layouts/community) is for your site's Community page. - -It also provides a [default "landing page" type of template](https://github.com/google/docsy/tree/main/layouts/_default) with the site header and footer, but no left nav, that you can use for any other section. In this site and our example site it's used for the site [home page](/) and the [About](/about/) page. - -Each top-level **section** in your site corresponds to a **directory** in your site content root. Hugo automatically applies the appropriate **template** for that section, depending on which folder the content is in. For example, this page is in the `docs` subdirectory of the site's content root directory `content/en/`, so Hugo automatically applies the `docs` template. You can override this by explicitly specifying a template or content type for a particular page. - -If you've copied the example site, you already have appropriately named top-level section directories for using Docsy's templates, each with an index page ( `_index.md` or `index.html`) page for users to land on. These top-level sections also appear in the example site's [top-level menu](/docs/adding-content/navigation/#top-level-menu). +Hugo builds your site pages using the content files you provide plus any +templates provided by your site's theme. These templates (or _"layouts"_ in Hugo +terminology) include things like your page's headers, footers, navigation, and +links to stylesheets: essentially, everything except your page's specific +content. The templates in turn can be made up of _partials_: little reusable +snippets of HTML for page elements like headers, search boxes, and more. + +Because most technical documentation sites have different sections for different +types of content, the Docsy theme comes with the +[following templates](https://github.com/google/docsy/tree/main/layouts) for +top-level site sections that you might need: + +- [`docs`](https://github.com/google/docsy/tree/main/layouts/docs) is for pages + in your site's Documentation section. +- [`blog`](https://github.com/google/docsy/tree/main/layouts/blog) is for pages + in your site's Blog. +- [`community`](https://github.com/google/docsy/tree/main/layouts/community) is + for your site's Community page. + +It also provides a +[default "landing page" type of template](https://github.com/google/docsy/tree/main/layouts/) +with the site header and footer, but no left nav, that you can use for any other +section. In this site and our example site it's used for the site [home page](/) +and the [About](/about/) page. + +Each top-level **section** in your site corresponds to a **directory** in your +site content root. Hugo automatically applies the appropriate **template** for +that section, depending on which folder the content is in. For example, this +page is in the `docs` subdirectory of the site's content root directory +`content/en/`, so Hugo automatically applies the `docs` template. You can +override this by explicitly specifying a template or content type for a +particular page. + +If you've copied the example site, you already have appropriately named +top-level section directories for using Docsy's templates, each with an index +page ( `_index.md` or `index.html`) page for users to land on. These top-level +sections also appear in the example site's +[top-level menu](/docs/adding-content/navigation/#top-level-menu). ### Custom sections -If you've copied the example site and *don't* want to use one of the provided content sections, just delete the appropriate content subdirectory. Similarly, if you want to add a top-level section, just add a new subdirectory, though you'll need to specify the layout or content type explicitly in the [frontmatter](#page-frontmatter) of each page if you want to use any existing Docsy template other than the default one. For example, if you create a new directory `content/en/amazing` and want one or more pages in that custom section to use Docsy's `docs` template, you add `type: docs` to the frontmatter of each page: - +If you've copied the example site and _don't_ want to use one of the provided +content sections, just delete the appropriate content subdirectory. Similarly, +if you want to add a top-level section, just add a new subdirectory, though +you'll need to specify the layout or content type explicitly in the +[frontmatter](#page-frontmatter) of each page if you want to use any existing +Docsy template other than the default one. For example, if you create a new +directory `content/en/amazing` and want one or more pages in that custom section +to use Docsy's `docs` template, you add `type: docs` to the frontmatter of each +page: + + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -64,21 +106,36 @@ description: > } {{< /tab >}} {{< /tabpane >}} + -Alternatively, create your own page template for your new section in your project's `layouts` directory based on one of the existing templates. +Alternatively, create your own page template for your new section in your +project's `layouts` directory based on one of the existing templates. -You can find out much more about how Hugo page layouts work in [Hugo Templates](https://gohugo.io/templates/). The rest of this page tells you about how to add content and use each of Docsy's templates. +You can find out much more about how Hugo page layouts work in +[Hugo Templates](https://gohugo.io/templates/). The rest of this page tells you +about how to add content and use each of Docsy's templates. ### Alternative site structure -As noted above, by default your site has a home page (using the `_default` layout), a docs section under `/docs/`, a blog section under `/blog/` and a community section under `/community/`. [The type](https://gohugo.io/content-management/types/) of each section (which determines the layout it uses) matches its directory name. +As noted above, by default your site has a home page, a docs section under +`/docs/`, a blog section under `/blog/` and a community section under +`/community/`. [The type](https://gohugo.io/content-management/types/) of each +section (which determines the layout it uses) matches its directory name. -In some cases, you may want to have a different directory structure, but still make use of Docsy's layouts. A common example is for a "docs site", where most of the pages (including the home page) use the docs layout, or perhaps you'd rather have a `/news/` directory treated with the blog layout. +In some cases, you may want to have a different directory structure, but still +make use of Docsy's layouts. A common example is for a "docs site", where most +of the pages (including the home page) use the docs layout, or perhaps you'd +rather have a `/news/` directory treated with the blog layout. -Since Hugo 0.76, this has become practical without copying layouts to your site, or having to specify `type: blog` on every single page by making use of [target specific cascading front matter](https://gohugo.io/content-management/front-matter/#target-specific-pages). +Since Hugo 0.76, this has become practical without copying layouts to your site, +or having to specify `type: blog` on every single page by making use of +[target specific cascading front matter](https://gohugo.io/content-management/front-matter/#target-specific-pages). -For example, for the `/news/` section, you can specify the following front matter in the index page which will change the type of the section and everything below it to "blog": +For example, for the `/news/` section, you can specify the following front +matter in the index page which will change the type of the section and +everything below it to "blog": + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -122,10 +179,13 @@ cascade: } {{< /tab >}} {{< /tabpane >}} + +If you want to create a "docs" site, specifying something like the following in +the top level `_index.md` will set all top level sections to be treated as +"docs", except for "news": -If you want to create a "docs" site, specifying something like the following in the top level `_index.md` will set all top level sections to be treated as "docs", except for "news": - + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -181,17 +241,28 @@ cascade: } {{< /tab >}} {{< /tabpane >}} + -Note the addition of `toc_root` here. Setting that to true for a section causes it to be treated as a separate part of the site, with its own left hand navigation menu. +Note the addition of `toc_root` here. Setting that to true for a section causes +it to be treated as a separate part of the site, with its own left hand +navigation menu. -An example docs-based site that uses this technique can be found at the [mostly docs](https://github.com/gwatts/mostlydocs/) repo. +An example docs-based site that uses this technique can be found at the +[mostly docs](https://github.com/gwatts/mostlydocs/) repo. ## Page frontmatter -Each page file in a Hugo site has metadata frontmatter that tells Hugo about the page. You specify page frontmatter in TOML, YAML, or JSON (our example site and this site use YAML). Use the frontmatter to specify the page title, description, creation date, link title, template, menu weighting, and even any resources such as images used by the page. You can see a complete list of possible page frontmatter in [Front Matter](https://gohugo.io/content-management/front-matter/). +Each page file in a Hugo site has metadata frontmatter that tells Hugo about the +page. You specify page frontmatter in TOML, YAML, or JSON (our example site and +this site use YAML). Use the frontmatter to specify the page title, description, +creation date, link title, template, menu weighting, and even any resources such +as images used by the page. You can see a complete list of possible page +frontmatter in +[Front Matter](https://gohugo.io/content-management/front-matter/). For example, here's the frontmatter for this page: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -222,21 +293,36 @@ description: > } {{< /tab >}} {{< /tabpane >}} + -The minimum frontmatter you need to provide is a title: everything else is up to you! However, if you leave out the page weight, your [navigation](/docs/adding-content/navigation) may get a little disorganized. You may also want to include `description` since Docsy uses that to generate the meta `description` tag used by search engines. See [Search Engine Optimization (SEO) meta tags]({{< ref "feedback#search-engine-optimization-meta-tags" >}}) for details. - +The minimum frontmatter you need to provide is a title: everything else is up to +you! However, if you leave out the page weight, your +[navigation](/docs/adding-content/navigation) may get a little disorganized. You +may also want to include `description` since Docsy uses that to generate the +meta `description` tag used by search engines. See [Search Engine Optimization +(SEO) meta tags]({{< ref "feedback#search-engine-optimization-meta-tags" >}}) +for details. ## Page contents and markup -By default you create pages in a Docsy site as simple [Markdown or HTML files](https://gohugo.io/content-management/formats/) with [page frontmatter](#page-frontmatter), as described above. -As of version 0.100, [Goldmark](https://github.com/yuin/goldmark/) is the only Markdown parser supported by Hugo. +By default you create pages in a Docsy site as simple +[Markdown or HTML files](https://gohugo.io/content-management/formats/) with +[page frontmatter](#page-frontmatter), as described above. As of version 0.100, +[Goldmark](https://github.com/yuin/goldmark/) is the only Markdown parser +supported by Hugo. -In addition to your marked-up text, you can also use Hugo and Docsy's [shortcodes](/docs/adding-content/shortcodes): reusable chunks of HTML that you can use to quickly build your pages. Find out more about shortcodes in [Docsy Shortcodes](/docs/adding-content/shortcodes). - -{{% alert title="Note" color="info" %}} -Hugo also supports adding content using other markups using [external parsers as helpers](https://gohugo.io/content-management/formats/#additional-formats-through-external-helpers). For example, you can add content in RST using `rst2html` as an external parser (though be aware this does not support all flavors of RST, such as Sphinx RST). Similarly, you can use `asciidoctor` to parse Asciidoc files, or `pandoc` for other formats. - -External parsers may not be suitable for use with all deployment options, as you'll need to install the external parser and run Hugo yourself to generate your site (so, for example, you won't be able to use [Netlify's continuous deployment feature](/docs/deployment/#deployment-with-netlify)). In addition, adding an external parser may cause performance issues building larger sites. -{{% /alert %}} +In addition to your marked-up text, you can also use Hugo and Docsy's +[shortcodes](/docs/adding-content/shortcodes): reusable chunks of HTML that you +can use to quickly build your pages. Find out more about shortcodes in +[Docsy Shortcodes](/docs/adding-content/shortcodes). + +{{% alert title="Note" color="info" %}} Hugo also supports adding content using +other markups using +[external parsers as helpers](https://gohugo.io/content-management/formats/#additional-formats-through-external-helpers). +For example, you can add content in RST using `rst2html` as an external parser +(though be aware this does not support all flavors of RST, such as Sphinx RST). +Similarly, you can use `asciidoctor` to parse Asciidoc files, or `pandoc` for +other formats. + +External parsers may not be suitable for use with all deployment options, as +you'll need to install the external parser and run Hugo yourself to generate +your site (so, for example, you won't be able to use +[Netlify's continuous deployment feature](/docs/deployment/#deployment-with-netlify)). +In addition, adding an external parser may cause performance issues building +larger sites. {{% /alert %}} ### Working with links -Hugo lets you specify links using normal Markdown syntax, though remember that you need to specify links relative to your site's root URL, and that relative URLs are left unchanged by Hugo in your site's generated HTML. +Hugo lets you specify links using normal Markdown syntax, though remember that +you need to specify links relative to your site's root URL, and that relative +URLs are left unchanged by Hugo in your site's generated HTML. -Alternatively you can use Hugo's helper [`ref` and `relref` shortcodes](https://gohugo.io/content-management/cross-references/) for creating internal links that resolve to the correct URL. However, be aware this means your links will not appear as links at all if a user views your page outside your generated site, for example using the rendered Markdown feature in GitHub's web UI. +Alternatively you can use Hugo's helper +[`ref` and `relref` shortcodes](https://gohugo.io/functions/relref/) for +creating internal links that resolve to the correct URL. However, be aware this +means your links will not appear as links at all if a user views your page +outside your generated site, for example using the rendered Markdown feature in +GitHub's web UI. -You can find (or add!) tips and gotchas for working with Hugo links in [Hugo Tips](/docs/best-practices/site-guidance). +You can find (or add!) tips and gotchas for working with Hugo links in +[Hugo Tips](/docs/best-practices/site-guidance). ### Content style -We don't mandate any particular style for your page contents. However, if you'd like some guidance on how to write and format clear, concise technical documentation, we recommend the [Google Developer Documentation Style Guide](https://developers.google.com/style/), particularly the [Style Guide Highlights](https://developers.google.com/style/highlights). +We don't mandate any particular style for your page contents. However, if you'd +like some guidance on how to write and format clear, concise technical +documentation, we recommend the +[Google Developer Documentation Style Guide](https://developers.google.com/style/), +particularly the +[Style Guide Highlights](https://developers.google.com/style/highlights). ## Page bundles -You can create site pages as standalone files in their section or subsection directory, or as folders where the content is in the folder's index page. Creating a folder for your page lets you [bundle](https://gohugo.io/content-management/page-bundles/) images and other resources together with the content. - -You can see examples of both approaches in this and our example site. For example, the source for this page is just a standalone file `/content/en/docs/adding-content.md`. However the source for [Docsy Shortcodes](/docs/adding-content/shortcodes/) in this site lives in `/content/en/docs/adding-content/shortcodes/index.md`, with the image resource used by the page in the same `/shortcodes/` directory. In Hugo terminology, this is called a *leaf bundle* because it's a folder containing all the data for a single site page without any child pages (and uses `index.md` without an underscore). - -You can find out much more about managing resources with Hugo bundles in [Page Bundles](https://gohugo.io/content-management/page-bundles/). +You can create site pages as standalone files in their section or subsection +directory, or as folders where the content is in the folder's index page. +Creating a folder for your page lets you +[bundle](https://gohugo.io/content-management/page-bundles/) images and other +resources together with the content. + +You can see examples of both approaches in this and our example site. For +example, the source for this page is just a standalone file +`/content/en/docs/adding-content.md`. However the source for +[Docsy Shortcodes](/docs/adding-content/shortcodes/) in this site lives in +`/content/en/docs/adding-content/shortcodes/index.md`, with the image resource +used by the page in the same `/shortcodes/` directory. In Hugo terminology, this +is called a _leaf bundle_ because it's a folder containing all the data for a +single site page without any child pages (and uses `index.md` without an +underscore). + +You can find out much more about managing resources with Hugo bundles in +[Page Bundles](https://gohugo.io/content-management/page-bundles/). ## Adding docs and blog posts -The template you'll probably use most often is the [`docs` template](https://github.com/google/docsy/blob/main/layouts/docs/baseof.html) (as used in this page) or the very similar [`blog` template](https://github.com/google/docsy/blob/main/layouts/blog/baseof.html). Both these templates include: +The template you'll probably use most often is the +[`docs` template](https://github.com/google/docsy/blob/main/layouts/docs/baseof.html) +(as used in this page) or the very similar +[`blog` template](https://github.com/google/docsy/blob/main/layouts/blog/baseof.html). +Both these templates include: -* a left nav -* GitHub links (populated from your site config) for readers to edit the page or create issues -* a page menu +- a left nav +- GitHub links (populated from your site config) for readers to edit the page or + create issues +- a page menu -as well as the common header and footer used by all your site's pages. Which template is applied depends on whether you've added the content to the `blog` or `docs` content directory. You can find out more about how the nav and page menu are created in [Navigation and Search](/docs/adding-content/navigation/). +as well as the common header and footer used by all your site's pages. Which +template is applied depends on whether you've added the content to the `blog` or +`docs` content directory. You can find out more about how the nav and page menu +are created in [Navigation and Search](/docs/adding-content/navigation/). ### Organizing your documentation -While Docsy's top-level sections let you create site sections for different types of content, you may also want to organize your docs content within your `docs` section. For example, this site's `docs` section directory has multiple subdirectories for **Getting Started**, **Content and Customization**, and so on. Each subdirectory has an `_index.md` (it could also be an `_index.html`), which acts as a section index page and tells Hugo that the relevant directory is a subsection of your docs. - -Docsy's `docs` layout gives you a left nav pane with an autogenerated nested menu based on your `docs` file structure. Each standalone page or subsection `_index.md` or `_index.html` page in the `docs/` directory gets a top level menu item, using the link name and `weight` metadata from the page or index. - -To add docs to a subsection, just add your page files to the relevant subdirectory. Any pages that you add to a subsection in addition to the subsection index page will appear in a submenu (look to the left to see one in action!), again ordered by page `weight`. Find out more about adding Docsy's navigation metadata in [Navigation and Search](/docs/adding-content/navigation/) - -If you've copied the example site, you'll already have some suggested subdirectories in your `docs` directory, with guidance for what types of content to put in them and some example Markdown pages. You can find out more about organizing your content with Docsy in [Organizing Your Content](/docs/best-practices/organizing-content/). +While Docsy's top-level sections let you create site sections for different +types of content, you may also want to organize your docs content within your +`docs` section. For example, this site's `docs` section directory has multiple +subdirectories for **Getting Started**, **Content and Customization**, and so +on. Each subdirectory has an `_index.md` (it could also be an `_index.html`), +which acts as a section index page and tells Hugo that the relevant directory is +a subsection of your docs. + +Docsy's `docs` layout gives you a left nav pane with an autogenerated nested +menu based on your `docs` file structure. Each standalone page or subsection +`_index.md` or `_index.html` page in the `docs/` directory gets a top level menu +item, using the link name and `weight` metadata from the page or index. + +To add docs to a subsection, just add your page files to the relevant +subdirectory. Any pages that you add to a subsection in addition to the +subsection index page will appear in a submenu (look to the left to see one in +action!), again ordered by page `weight`. Find out more about adding Docsy's +navigation metadata in [Navigation and Search](/docs/adding-content/navigation/) + +If you've copied the example site, you'll already have some suggested +subdirectories in your `docs` directory, with guidance for what types of content +to put in them and some example Markdown pages. You can find out more about +organizing your content with Docsy in +[Organizing Your Content](/docs/best-practices/organizing-content/). #### Docs section landing pages -By default a docs section landing page (the `_index.md` or `_index.html` in the section directory) uses a layout that adds a formatted list of links to the pages in the section, with their frontmatter descriptions. The [Content and Customization](/docs/adding-content/) landing page in this site is a good example. +By default a docs section landing page (the `_index.md` or `_index.html` in the +section directory) uses a layout that adds a formatted list of links to the +pages in the section, with their frontmatter descriptions. The +[Content and Customization](/docs/adding-content/) landing page in this site is +a good example. -To display a simple bulleted list of links to the section's pages instead, specify `simple_list: true` in the landing page's frontmatter: +To display a simple bulleted list of links to the section's pages instead, +specify `simple_list: true` in the landing page's frontmatter: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -344,9 +500,12 @@ weight: 20 } {{< /tab >}} {{< /tabpane >}} + -To display no links at all, specify `no_list: true` in the landing page's frontmatter: +To display no links at all, specify `no_list: true` in the landing page's +frontmatter: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -371,13 +530,24 @@ weight: 20 } {{< /tab >}} {{< /tabpane >}} + ### Organizing your blog posts -Docsy's `blog` layout also gives you a left nav menu (like the `docs` layout), and a list-type index page for your blog that's applied to `/blog/_index.md` and automatically displays snippets of all your recent posts in reverse chronological order. +Docsy's `blog` layout also gives you a left nav menu (like the `docs` layout), +and a list-type index page for your blog that's applied to `/blog/_index.md` and +automatically displays snippets of all your recent posts in reverse +chronological order. -To create different blog categories to organize your posts, create subfolders in `blog/`. For instance, in our [example site](https://github.com/google/docsy-example/tree/main/content/en/blog) we have `news` and `releases`. Each category needs to have its own `_index.md` or `_index.html` landing page file specifying the category title for it to appear properly in the left nav and top-level blog landing page. Here's the index page for `releases`: +To create different blog categories to organize your posts, create subfolders in +`blog/`. For instance, in our +[example site](https://github.com/google/docsy-example/tree/main/content/en/blog) +we have `news` and `releases`. Each category needs to have its own `_index.md` +or `_index.html` landing page file specifying the category title for it to +appear properly in the left nav and top-level blog landing page. Here's the +index page for `releases`: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -402,9 +572,12 @@ weight: 20 } {{< /tab >}} {{< /tabpane >}} + -To add author and date information to blog posts, add them to the page frontmatter: +To add author and date information to blog posts, add them to the page +frontmatter: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -456,30 +629,53 @@ resources: } {{< /tab >}} {{< /tabpane >}} + -If you've copied the example site and you don't want a blog section, or want to link to an external blog instead, just delete the `blog` subdirectory. - +If you've copied the example site and you don't want a blog section, or want to +link to an external blog instead, just delete the `blog` subdirectory. ## Working with top-level landing pages. -Docsy's [default page template](https://github.com/google/docsy/blob/main/layouts/docs/baseof.html) has no left nav and is useful for creating a home page for your site or other "landing" type pages. +Docsy's +[default page template](https://github.com/google/docsy/blob/main/layouts/docs/baseof.html) +has no left nav and is useful for creating a home page for your site or other +"landing" type pages. ### Customizing the example site pages -If you've copied the example site, you already have a simple site landing page in `content/en/_index.html`. This is made up of Docsy's provided Hugo shortcode [page blocks](/docs/adding-content/shortcodes/#shortcode-blocks). +If you've copied the example site, you already have a simple site landing page +in `content/en/_index.html`. This is made up of Docsy's provided Hugo shortcode +[page blocks](/docs/adding-content/shortcodes/#shortcode-blocks). -To customize the large landing image, which is in a [cover](/docs/adding-content/shortcodes/#blockscover) block, replace the `content/en/featured-background.jpg` file in your project with your own image (it can be called whatever you like as long as it has `background` in the file name). You can remove or add as many blocks as you like, as well as adding your own custom content. +To customize the large landing image, which is in a +[cover](/docs/adding-content/shortcodes/#blockscover) block, replace the +`content/en/featured-background.jpg` file in your project with your own image +(it can be called whatever you like as long as it has `background` in the file +name). You can remove or add as many blocks as you like, as well as adding your +own custom content. -The example site also has an About page in `content/en/about/_index.html` using the same Docsy template. Again, this is made up of [page blocks](/docs/adding-content/shortcodes/#shortcode-blocks), including another background image in `content/en/about/featured-background.jpg`. As with the site landing page, you can replace the image, remove or add blocks, or just add your own content. +The example site also has an About page in `content/en/about/_index.html` using +the same Docsy template. Again, this is made up of +[page blocks](/docs/adding-content/shortcodes/#shortcode-blocks), including +another background image in `content/en/about/featured-background.jpg`. As with +the site landing page, you can replace the image, remove or add blocks, or just +add your own content. ### Building your own landing pages -If you've just used the theme, you can still use all Docsy's provided [page blocks](/docs/adding-content/shortcodes/#shortcode-blocks) (or any other content you want) to build your own landing pages in the same file locations. +If you've just used the theme, you can still use all Docsy's provided +[page blocks](/docs/adding-content/shortcodes/#shortcode-blocks) (or any other +content you want) to build your own landing pages in the same file locations. ## Adding a community page -The `community` landing page template has boilerplate content that's automatically filled in with the project name and community links specified in `hugo.toml`/`hugo.yaml`/`hugo.json`, providing your users with quick links to resources that help them get involved in your project. The same links are also added by default to your site footer. +The `community` landing page template has boilerplate content that's +automatically filled in with the project name and community links specified in +`hugo.toml`/`hugo.yaml`/`hugo.json`, providing your users with quick links to +resources that help them get involved in your project. The same links are also +added by default to your site footer. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -596,72 +792,80 @@ params: } {{< /tab >}} {{< /tabpane >}} + -If you're creating your own site and want to add a page using this template, add a `/community/_index.md` file in your content root directory. If you've copied the example site and *don't* want a community page, just delete the `/content/en/community/` directory in your project repo. +If you're creating your own site and want to add a page using this template, add +a `/community/_index.md` file in your content root directory. If you've copied +the example site and _don't_ want a community page, just delete the +`/content/en/community/` directory in your project repo. -## Adding static content +By default, Docsy layouts assume that your project's contributing page is found +at `/docs/contribution-guidelines`. To specify another URL, add it to +the front matter of `/community/_index.md` as illustrated next. The URL can be +an external URL or a local path: -You may want to serve some non-Hugo-built content along with your site: for example, if you have generated reference docs using Doxygen, Javadoc, or other doc generation tools. +```yaml +params: + contributingUrl: docs/contributing/ +``` -To add static content to be served "as-is", just add the content as a folder and/or files in your site's `static` directory. When your site is deployed, content in this directory is served at the site root path. So, for example, if you have added content at `/static/reference/cpp/`, users can access that content at `http://{server-url}/reference/cpp/` and you can link to pages in this directory from other pages at `/reference/cpp/{file name}`. +## Adding static content -You can also use this directory for other files used by your project, including image files. You can find out more about serving static files, including configuring multiple directories for static content, in [Static Files](https://gohugo.io/content-management/static-files/). +You may want to serve some non-Hugo-built content along with your site: for +example, if you have generated reference docs using Doxygen, Javadoc, or other +doc generation tools. -## RSS feeds +To add static content to be served "as-is", just add the content as a folder +and/or files in your site's `static` directory. When your site is deployed, +content in this directory is served at the site root path. So, for example, if +you have added content at `/static/reference/cpp/`, users can access that +content at `http://{server-url}/reference/cpp/` and you can link to pages in +this directory from other pages at `/reference/cpp/{file name}`. -Hugo will, by default, create an RSS feed for the home page and any section. For the main RSS feed you can control which sections to include by setting a site param in your `hugo.toml`/`hugo.yaml`/`hugo.json`. This is the default configuration: +You can also use this directory for other files used by your project, including +image files. You can find out more about serving static files, including +configuring multiple directories for +[static content](https://gohugo.io/getting-started/directory-structure/#static). -{{< tabpane >}} -{{< tab header="Configuration file:" disabled=true />}} -{{< tab header="hugo.toml" lang="toml" >}} -[params] -rss_sections = ["blog"] -{{< /tab >}} -{{< tab header="hugo.yaml" lang="yaml" >}} -params: - rss_sections: [blog] -{{< /tab >}} -{{< tab header="hugo.json" lang="json" >}} -{ - "params": { - "rss_sections": [ - "blog" - ] - } -} -{{< /tab >}} -{{< /tabpane >}} +## RSS feeds -To disable all RSS feeds, add the following to your `hugo.toml`/`hugo.yaml`/`hugo.json`: +Hugo will, by default, create an RSS feed for the home page and any section. To +disable all RSS feeds, add the following to your +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} -[params] disableKinds = ["RSS"] {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -params: - disableKinds: [RSS] +disableKinds: [RSS] {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "params": { - "disableKinds": [ - "RSS" - ] - } + "disableKinds": [ + "RSS" + ] } {{< /tab >}} {{< /tabpane >}} - + ## Sitemap -Hugo creates a `sitemap.xml` file for your generated site by default: for example, [here's the sitemap](/sitemap.xml) for this site. +Hugo creates a `sitemap.xml` file for your generated site by default: for +example, [here's the sitemap](/sitemap.xml) for this site. -You can configure the frequency with which your sitemap is updated, your sitemap filename, and the default page priority in your `hugo.toml`/`hugo.yaml`/`hugo.json`: +You can configure the frequency with which your sitemap is updated, your sitemap +filename, and the default page priority in your +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -719,9 +928,12 @@ sitemap: } {{< /tab >}} {{< /tabpane >}} + -To override any of these values for a given page, specify it in page frontmatter: +To override any of these values for a given page, specify it in page +frontmatter: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -759,5 +971,7 @@ sitemap: } {{< /tab >}} {{< /tabpane >}} + -To learn more about configuring sitemaps, see [Sitemap Template](https://gohugo.io/templates/sitemap-template/). +To learn more about configuring sitemaps, see +[Sitemap Template](https://gohugo.io/templates/sitemap-template/). diff --git a/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md b/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md index 21163d946f..46c82a09c0 100644 --- a/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md +++ b/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md @@ -6,67 +6,165 @@ math: true chem: true --- -Docsy has built-in support for a number of diagram creation and typesetting tools you can use to add rich content to your site, including \\(\KaTeX\\), Mermaid, Diagrams.net, PlantUML, and MarkMap. - -## \\(\LaTeX\\) support with \\(\KaTeX\\) - -[\\(\LaTeX\\)](https://www.latex-project.org/) is a high-quality typesetting system for the production of technical and scientific documentation. Due to its excellent math typesetting capabilities, \\(\TeX\\) became the de facto standard for the communication and publication of scientific documents, especially if these documents contain a lot of mathematical formulae. Designed and mostly written by Donald Knuth, the initial version was released in 1978. Dating back that far, \\(\LaTeX\\) has `pdf` as its primary output target and is not particularly well suited for producing HTML output for the Web. Fortunately, with [\\(\KaTeX\\)](https://katex.org/) there exists a fast and easy-to-use JavaScript library for \\(\TeX\\) math rendering on the web, which was integrated into the Docsy theme. - -With \\(\KaTeX\\) support [enabled](#activating-and-configuring-katex-support) in Docsy, you can include complex mathematical formulae into your web page, either inline or centred on its own line. Since \\(\KaTeX\\) relies on server side rendering, it produces the same output regardless of your browser or your environment. Formulae can be shown either inline or in display mode: +Docsy has built-in support for a number of diagram creation and typesetting +tools you can use to add rich content to your site, including \(\KaTeX\), +Mermaid, Diagrams.net, PlantUML, and MarkMap. + +## \\(\\LaTeX\\) support with \\(\\KaTeX\\) + +[\(\LaTeX\)](https://www.latex-project.org/) is a high-quality typesetting +system for the production of technical and scientific documentation. Due to its +excellent math typesetting capabilities, \(\TeX\) became the de facto standard +for the communication and publication of scientific documents, especially if +these documents contain a lot of mathematical formulae. Designed and mostly +written by Donald Knuth, the initial version was released in 1978. Dating back +that far, \(\LaTeX\) has `pdf` as its primary output target and is not +particularly well suited for producing HTML output for the Web. Fortunately, +with [\(\KaTeX\)](https://katex.org/) there exists a fast and easy-to-use +JavaScript library for \(\TeX\) math rendering on the web, which was integrated +into the Docsy theme. + +With \(\KaTeX\) support [enabled](#activating-and-configuring-katex-support) in +Docsy, you can include complex mathematical formulae into your web page, either +inline or centred on its own line. Since \(\KaTeX\) relies on server side +rendering, it produces the same output regardless of your browser or your +environment. Formulae can be shown either inline or in display mode: ### Inline formulae The following code sample produces a text line with three inline formulae: ```tex -When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\\). +When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c= 0\) and they are \(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\). ``` -When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c= 0\\) and they are \\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\\). +When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c= 0\) and they are +\(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\). ### Formulae in display mode -The following code sample produces an introductory text line followed by a formula numbered as `(1)` residing on its own line: +The following code sample produces an introductory text line followed by a +formula numbered as `(1)` residing on its own line: + ````markdown -The probability of getting \\(k\\) heads when flipping \\(n\\) coins is: +The probability of getting \(k\) heads when flipping \(n\) coins is: +\[ +\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k} +\] +```` + + +As an alternative to the standard syntax used above, formulae can also be +authored using a +[GLFM math block](https://docs.gitlab.com/ee/user/markdown.html#math): + +````markdown +The probability of getting \(k\) heads when flipping \(n\) coins is: + ```math \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k} ``` ```` -The formula itself is written inside a [GLFM math block](https://docs.gitlab.com/ee/user/markdown.html#math). The above code fragment renders to: +Both standard syntax and `math` block render to the same formula: + +The probability of getting \(k\) heads when flipping \(n\) coins is: -The probability of getting \\(k\\) heads when flipping \\(n\\) coins is: ```math \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k} ``` -{{% alert title="Warning" color="warning" %}} -`math` code blocks are only supported as of hugo version 0.93. +{{% alert title="Warning" color="warning" %}} In order to display mathematical +formulae and/or chemical equations in your page(s), you need to run Hugo version +0.141.0 or above. With older Hugo versions, an error is thrown. {{% /alert %}} -In case of hugo version 0.92 or lower, use this code snippet to display the formula: -```tex -$$ -\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k} -$$ -``` -{{% /alert %}} +{{% alert title="Tip" %}} This +[wiki page](https://en.wikibooks.org/wiki/LaTeX/Mathematics) provides in-depth +information about typesetting mathematical formulae using the \(\LaTeX\) +typesetting system. {{% /alert %}} -{{% alert title="Tip" %}} -This [wiki page](https://en.wikibooks.org/wiki/LaTeX/Mathematics) provides in-depth information about typesetting mathematical formulae using the \\(\LaTeX\\) typesetting system. -{{% /alert %}} +### \\(\\LaTeX\\) typesetting using standard syntax -### Activating and configuring \\(\KaTeX\\) support +As of Hugo v0.122, you can enable \(\LaTeX\) typesetting in Markdown using the +standard syntax. To do so, use the goldmark `passthrough` extension inside your +`hugo.toml`/`hugo.yaml`/`hugo.json`: + + +{{< tabpane >}} +{{< tab header="Site configuration file:" disabled=true />}} +{{< tab header="hugo.toml" lang="toml" >}} +[markup] + [markup.goldmark] + [markup.goldmark.extensions] + [markup.goldmark.extensions.passthrough] + enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] +{{< /tab >}} +{{< tab header="hugo.yaml" lang="yaml" >}} +markup: + goldmark: + extensions: + passthrough: + enable: true + delimiters: + block: [['\[', '\]'], ['$$', '$$']] + inline: [['\(', '\)']] +{{< /tab >}} +{{< tab header="hugo.json" lang="json" >}} +{ + "markup": { + "goldmark": { + "extensions": { + "passthrough": { + "delimiters": { + "block": [ + [ + "\\[", + "\\]" + ], + [ + "$$", + "$$" + ] + ], + "inline": [ + [ + "\\(", + "\\)" + ] + ] + }, + "enable": true + } + } + } + } +} +{{< /tab >}} +{{< /tabpane >}} + + +You can edit this definition to meet your own needs. For details, see the +official [Hugo docs](https://gohugo.io/content-management/mathematics/#step-1). + +### Activating and configuring \\(\\KaTeX\\) support #### Auto activation -As soon as you use a `math` code block on your page, support of \\(\KaTeX\\) is automatically enabled. +As soon as you use a `math` code block on your page, support of \(\KaTeX\) is +automatically enabled. -#### Manual activation (no `math` code block present or hugo 0.92 or lower) +#### Manual activation (use of standard syntax, no `math` code block present) -If you want to use inline formulae and don't have a `math` code block present in your page which triggers auto activation, you need to manually activate \\(\KaTeX\\) support. The easiest way to do so is to add a `math` attribute to the frontmatter of your page and set it to `true`: +If you want to use formulae (block or inline) and don't have a `math` code block +present in your page which triggers auto activation, you need to manually +activate \(\KaTeX\) support. The easiest way to do so is to add a `math` +attribute to the frontmatter of your page and set it to `true`: + {{< tabpane >}} {{< tab header="Page front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -85,9 +183,13 @@ math: true } {{< /tab >}} {{< /tabpane >}} + -If you use formulae in most of your pages, you can also enable sitewide \\(\KaTeX\\) support inside the Docsy theme. To do so update `hugo.toml`/`hugo.yaml`/`hugo.json`: +If you use formulae in most of your pages, you can also enable sitewide +\(\KaTeX\) support inside the Docsy theme. To do so update +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Site configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -109,9 +211,38 @@ params: } {{< /tab >}} {{< /tabpane >}} + -Additionally, you can customize various \\(\KaTeX\\) options inside `hugo.toml`/`hugo.yaml`/`hugo.json`, if needed: +By default, Docsy pulls in the latest officially released version of \(\KaTeX\) +/ mhchem extension at build time. If that doesn't fit your needs, you can +specify the \(\KaTeX\) version you want in your configuration file +`hugo.toml`/`hugo.yaml`/`hugo.json`: + +{{< tabpane >}} +{{< tab header="Configuration file:" disabled=true />}} +{{< tab header="hugo.toml" lang="toml" >}} +[params.katex] +version = "0.16.22" +{{< /tab >}} +{{< tab header="hugo.yaml" lang="yaml" >}} +params: + katex: + version: 0.16.22 +{{< /tab >}} +{{< tab header="hugo.json" lang="json" >}} +{ + "params": { + "katex": { + "version": "0.16.22" + } + } +} +{{< /tab >}} +{{< /tabpane >}} + + + {{< tabpane >}} {{< tab header="Site configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -221,68 +352,107 @@ params: } {{< /tab >}} {{< /tabpane >}} + -For a complete list of options and their detailed description, have a look at the documentation of \\({\KaTeX}'s\\) [Rendering API options](https://katex.org/docs/autorender.html#api) and of \\({\KaTeX}'s\\) [configuration options](https://katex.org/docs/options.html). +{{% alert title="Note" %}} If you define custom delimiters, please make sure +they match with the delimiters defined +[above](#latex-typesetting-using-standard-syntax) as passthrough extension. +{{% /alert %}} + +For a complete list of options and their detailed description, have a look at +the documentation of \({\KaTeX}'s\) +[Rendering API options](https://katex.org/docs/autorender.html#api) and of +\({\KaTeX}'s\) [configuration options](https://katex.org/docs/options.html). ### Display of Chemical Equations and Physical Units -[mhchem](https://www.ctan.org/pkg/mhchem) is a \\(\LaTeX\\) package for typesetting chemical molecular formulae and equations. Fortunately, \\(\KaTeX\\) provides the `mhchem` [extension](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem) that makes the `mhchem` package accessible when authoring content for the web. With `mhchem` extension [enabled](#activating-rendering-support-for-chemical-formulae), you can easily include chemical equations into your page. An equation can be shown either inline or can reside on its own line. The following code sample produces a text line including a chemical equation: +[mhchem](https://www.ctan.org/pkg/mhchem) is a \(\LaTeX\) package for +typesetting chemical molecular formulae and equations. Fortunately, \(\KaTeX\) +provides the `mhchem` +[extension](https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem) that makes +the `mhchem` package accessible when authoring content for the web. With +`mhchem` extension +[enabled](#activating-rendering-support-for-chemical-equations), you can easily +include chemical equations into your page. An equation can be shown either +inline or can reside on its own line. The following code sample produces a text +line including a chemical equation: ```mhchem -*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\) +*Precipitation of barium sulfate:* \(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\) ``` -*Precipitation of barium sulfate:* \\(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\\) +_Precipitation of barium sulfate:_ \(\ce{SO4^2- + Ba^2+ -> BaSO4 v}\) -More complex equations need to be displayed on their own line. Use a code block adorned with `chem` in order to achieve this: +More complex equations can be displayed on their own line using the block +delimiters defined: + ````markdown -```chem +\[ \tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$} -``` +\] ```` + +Alternatively, you can use a code block adorned with `chem` in order to render +the equation: + +````markdown ```chem \tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$} ``` +```` -{{% alert title="Warning" color="warning" %}} -`chem` code blocks are only supported as of hugo version 0.93. +Both standard syntax and `chem` block renders to the same equation: -In case of hugo version 0.92 or lower, use this code snippet to display the formula: -```tex -$$ + +\[ \tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$} -$$ -``` -{{% /alert %}} +\] + -{{% alert title="Note" %}} -The [manual](https://mhchem.github.io/MathJax-mhchem/) for mchem’s input syntax provides in-depth information about typesetting chemical formulae and physical units using the `mhchem` tool. -{{% /alert %}} +{{% alert title="Note" %}} The +[manual](https://mhchem.github.io/MathJax-mhchem/) for mchem’s input syntax +provides in-depth information about typesetting chemical formulae and physical +units using the `mhchem` tool. {{% /alert %}} + +Use of `mhchem` is not limited to the authoring of chemical equations. By using +the included `\pu` command, pretty looking physical units can be written with +ease, too. The following code sample produces two text lines with four numbers +plus their corresponding physical units: -Use of `mhchem` is not limited to the authoring of chemical equations, using the included `\pu` command, pretty looking physical units can be written with ease, too. The following code sample produces two text lines with four numbers plus their corresponding physical units: +Use of `mhchem` is not limited to the authoring of chemical equations, using the +included `\pu` command, pretty looking physical units can be written with ease, +too. The following code sample produces two text lines with four numbers plus +their corresponding physical units: ```mhchem -* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) \\ -* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\) +* Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\) \\ +* Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\) ``` -* Scientific number notation: \\(\pu{1.2e3 kJ}\\) or \\(\pu{1.2E3 kJ}\\) -* Divisions: \\(\pu{123 kJ/mol}\\) or \\(\pu{123 kJ//mol}\\) +- Scientific number notation: \(\pu{1.2e3 kJ}\) or \(\pu{1.2E3 kJ}\) +- Divisions: \(\pu{123 kJ/mol}\) or \(\pu{123 kJ//mol}\) -For a complete list of options when authoring physical units, have a look at the [section](https://mhchem.github.io/MathJax-mhchem/#pu) on physical units in the `mhchem` documentation. +For a complete list of options when authoring physical units, have a look at the +[section](https://mhchem.github.io/MathJax-mhchem/#pu) on physical units in the +`mhchem` documentation. -#### Activating rendering support for chemical formulae +#### Activating rendering support for chemical equations ##### Auto activation -As soon as you use a `chem` code block on your page, rendering support for chemical equations is automatically enabled. +As soon as you use a `chem` code block on your page, rendering support for +chemical equations is automatically enabled. -##### Manual activation (no `chem` code block present or hugo 0.92 or lower) +##### Manual activation (use of standard syntax, no `chem` code block present) -If you want to use chemical formulae inline and don't have a `chem` code block present in your page which triggers auto activation, you need to manually activate rendering support for chemical formulae. The easiest way to do so is to add a `chem` attribute to the frontmatter of your page and set it to `true`: +If you want to use chemical formulae inline and don't have a `chem` code block +present in your page which triggers auto activation, you need to manually +activate rendering support for chemical formulae. The easiest way to do so is to +add a `chem` attribute to the frontmatter of your page and set it to `true`: + {{< tabpane >}} {{< tab header="Page front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -301,9 +471,13 @@ chem: true } {{< /tab >}} {{< /tabpane >}} + -If you use formulae in most of your pages, you can also enable sitewide rendering support for chemical formulae inside the Docsy theme. To do so, enable `mhchem` inside your `hugo.toml`/`hugo.yaml`/`hugo.json`: +If you use formulae in most of your pages, you can also enable sitewide +rendering support for chemical formulae inside the Docsy theme. To do so, enable +`mhchem` inside your `hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Site configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -333,14 +507,22 @@ params: } {{< /tab >}} {{< /tabpane >}} + ## Diagrams with Mermaid -[Mermaid](https://mermaid-js.github.io) is a Javascript library for rendering simple text definitions to useful diagrams in the browser. It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts. +[Mermaid](https://mermaid-js.github.io) is a Javascript library for rendering +simple text definitions to useful diagrams in the browser. It can generate a +variety of different diagram types, including flowcharts, sequence diagrams, +class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts +and pie charts. -With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser as soon as the page loads. +With Mermaid support enabled in Docsy, you can include the text definition of a +Mermaid diagram inside a code block, and it will automatically be rendered by +the browser as soon as the page loads. -The great advantage of this is anyone who can edit the page can now edit the diagram - no more hunting for the original tools and version to make a new edit. +The great advantage of this is anyone who can edit the page can now edit the +diagram - no more hunting for the original tools and version to make a new edit. For example, the following defines a sequence diagram: @@ -380,34 +562,41 @@ sequenceDiagram Docsy user->>Docsy user: Being happy ``` -Support of Mermaid diagrams is automatically enabled as soon as you use a `mermaid` code block on your page. +Support of Mermaid diagrams is automatically enabled as soon as you use a +`mermaid` code block on your page. -By default, docsy pulls in the latest officially released version of Mermaid at build time. If that doesn't fit your needs, you can specify the wanted mermaid version inside your configuration file `hugo.toml`/`hugo.yaml`/`hugo.json`: +By default, Docsy pulls in the latest officially released version of Mermaid at +build time. If that doesn't fit your needs, you can specify the wanted mermaid +version inside your configuration file `hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params.mermaid] -version = "10.9.0" +version = "11.6.0" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} params: mermaid: - version: 10.9.0 + version: 11.6.0 {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "params": { "mermaid": { - "version": "10.9.0" + "version": "11.6.0" } } } {{< /tab >}} {{< /tabpane >}} + -If needed, you can define custom settings for your diagrams, such as themes, padding in your `hugo.toml`/`hugo.yaml`/`hugo.json`. +If needed, you can define custom settings for your diagrams, such as themes, +padding in your `hugo.toml`/`hugo.yaml`/`hugo.json`. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -437,16 +626,28 @@ params: } {{< /tab >}} {{< /tabpane >}} + -See the [Mermaid documentation](https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults) for a list of defaults that can be overridden. +See the +[Mermaid documentation](https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults) +for a list of defaults that can be overridden. -Settings can also be overridden on a per-diagram basis by making use of a [frontmatter config](http://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables) block at the start of the diagram definition. +Settings can also be overridden on a per-diagram basis by making use of a +[frontmatter config](https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables) +block at the start of the diagram definition. ## UML Diagrams with PlantUML -[PlantUML](https://plantuml.com/en/) is an alternative to Mermaid that lets you quickly create UML diagrams, including sequence diagrams, use case diagrams, and state diagrams. Unlike Mermaid diagrams, which are entirely rendered in the browser, PlantUML uses a PlantUML server to create diagrams. You can use the provided default demo server (not recommended for production use), or run a server yourself. PlantUML offers a wider range of image types than Mermaid, so may be a better choice for some use cases. +[PlantUML](https://plantuml.com/en/) is an alternative to Mermaid that lets you +quickly create UML diagrams, including sequence diagrams, use case diagrams, and +state diagrams. Unlike Mermaid diagrams, which are entirely rendered in the +browser, PlantUML uses a PlantUML server to create diagrams. You can use the +provided default demo server (not recommended for production use), or run a +server yourself. PlantUML offers a wider range of image types than Mermaid, so +may be a better choice for some use cases. -Diagrams are defined using a simple and intuitive language. ([see PlantUML Language Reference Guide](https://plantuml.com/en/guide)). +Diagrams are defined using a simple and intuitive language. +([see PlantUML Language Reference Guide](https://plantuml.com/en/guide)). The following example shows a use case diagram: @@ -492,6 +693,7 @@ Foo -> Foo7: To queue To enable/disable PlantUML, update `hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -513,9 +715,11 @@ params: } {{< /tab >}} {{< /tabpane >}} + Other optional settings are: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -558,10 +762,12 @@ params: } {{< /tab >}} {{< /tabpane >}} + ## MindMap support with MarkMap -[MarkMap](https://markmap.js.org/) is a Javascript library for rendering simple text definitions to MindMap in the browser. +[MarkMap](https://markmap.js.org/) is a Javascript library for rendering simple +text definitions to MindMap in the browser. For example, the following defines a simple MindMap: @@ -590,13 +796,13 @@ For example, the following defines a simple MindMap: ```js console.log('code block'); ``` -- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ +- KaTeX - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ ``` ```` Automatically renders to: -```markmap +````markmap # markmap ## Links @@ -620,11 +826,12 @@ Automatically renders to: ```js console.log('code block'); ``` -- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ -``` +- KaTeX - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ +```` To enable/disable MarkMap, update `hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -646,26 +853,37 @@ params: } {{< /tab >}} {{< /tabpane >}} + ## Diagrams with Diagrams.net -[Diagrams.net](https://diagrams.net/) (aka `draw.io`) provides a free and open source diagram editor that can generate a wider range of diagrams than Mermaid or PlantUML using a web or desktop editor. - -SVG and PNG files exported with the tool contain the source code of the original diagram by default, which allows the diagrams.net site to import those images again for edit in the future. With `draw.io` enabled, Docsy will detect this and automatically add an `Edit` button over any image that can be edited using the online site. +[Diagrams.net](https://diagrams.net/) (aka `draw.io`) provides a free and open +source diagram editor that can generate a wider range of diagrams than Mermaid +or PlantUML using a web or desktop editor. -Hover over the image below and click edit to instantly start working with it. Clicking the `Save` button will cause the edited diagram to be exported using the same filename and filetype, and downloaded to your browser. +SVG and PNG files exported with the tool contain the source code of the original +diagram by default, which allows the diagrams.net site to import those images +again for edit in the future. With `draw.io` enabled, Docsy will detect this and +automatically add an `Edit` button over any image that can be edited using the +online site. -{{%alert title="Note" color="primary" %}} -If you're creating a new diagram, be sure to `File -> Export` in either `svg` or `png` format (`svg` is usually the best choice) and ensure the `Include a copy of my diagram` is selected so it can be edited again later. -{{%/alert%}} +Hover over the image below and click edit to instantly start working with it. +Clicking the `Save` button will cause the edited diagram to be exported using +the same filename and filetype, and downloaded to your browser. -As the diagram data is transported via the browser, the diagrams.net server does not need to access the content on your Docsy server directly at all. +{{%alert title="Note" color="primary" %}} If you're creating a new diagram, be +sure to `File -> Export` in either `svg` or `png` format (`svg` is usually the +best choice) and ensure the `Include a copy of my diagram` is selected so it can +be edited again later. {{%/alert%}} +As the diagram data is transported via the browser, the diagrams.net server does +not need to access the content on your Docsy server directly at all. {{< figure src="docsy-diagrams.svg" caption="Mouse over the above image and click the `Edit` button!">}} To enable detection of diagrams, update `hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -687,9 +905,14 @@ params: } {{< /tab >}} {{< /tabpane >}} + -You can also [deploy and use your own server](https://github.com/jgraph/docker-drawio/blob/master/README.md) for editing diagrams, in which case update the configuration to point to that server: +You can also +[deploy and use your own server](https://github.com/jgraph/docker-drawio/blob/master/README.md) +for editing diagrams, in which case update the configuration to point to that +server: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -711,3 +934,4 @@ params: } {{< /tab >}} {{< /tabpane >}} + diff --git a/userguide/content/en/docs/adding-content/feedback.md b/userguide/content/en/docs/adding-content/feedback.md index edde20dabd..c1b83260ef 100644 --- a/userguide/content/en/docs/adding-content/feedback.md +++ b/userguide/content/en/docs/adding-content/feedback.md @@ -10,7 +10,7 @@ weight: 8 ## Adding Analytics The Docsy theme builds upon [Hugo's support for Google Analytics][hugo-ga], -which Hugo provides through [internal templates][]. Once you set up analytics as +which Hugo provides through [embedded templates][]. Once you set up analytics as described below, usage information for your site (such as page views) is sent to your [Google Analytics][] account. @@ -23,8 +23,8 @@ started** section of [Introducing Google Analytics 4 (GA4)][ga4-intro]. {{% alert title="Tip" %}} - Your project's **analytics ID** is a string that starts with `G-` (a GA4 - measurement ID) or `UA-` (a universal analytics property ID). +Your project's **analytics ID** is a string that starts with `G-` (a GA4 +measurement ID) or `UA-` (a universal analytics property ID). {{% /alert %}} @@ -33,55 +33,34 @@ started** section of [Introducing Google Analytics 4 (GA4)][ga4-intro]. Enable Google Analytics by adding your project's analytics ID to the site configuration file. For details, see [Configure Google Analytics][]. -By default, Docsy uses the [gtag.js][] analytics library for both GA4 (which -_requires_ `gtag.js`) and Universal Analytics (UA) site tags. If you prefer using -the older `analytics.js` library for your UA site tag, then set -`params.disableGtagForUniversalAnalytics` to `true` in your project's [configuration file]. - -{{< tabpane >}} -{{< tab header="Configuration file:" disabled=true />}} -{{< tab header="hugo.toml" lang="toml" >}} -[params] -disableGtagForUniversalAnalytics = true -{{< /tab >}} -{{< tab header="hugo.yaml" lang="yaml" >}} -params: - disableGtagForUniversalAnalytics: true -{{< /tab >}} -{{< tab header="hugo.json" lang="json" >}} -{ - "params": { - "disableGtagForUniversalAnalytics": true - } -} -{{< /tab >}} -{{< /tabpane >}} - {{% alert title="Deprecation note and warning" color="warning" %}} + - While you can configure your project's analytics ID by setting either the - top-level `googleAnalytics` config parameter or `services.googleAnalytics.id`, - **`googleAnalytics` was [deprecated in Hugo 0.120.0][v0.120.0]** and - will be removed in a future release. +While you can configure your project's analytics ID by setting either the +top-level `googleAnalytics` config parameter or `services.googleAnalytics.id`, +**`googleAnalytics` was [deprecated in Hugo 0.120.0][v0.120.0]** and will be +removed in a future release. - **Do not define both parameters,** otherwise this can result in [unexpected - behavior][]. For details, see [Is services.googleAnalytics.id an alias for - googleAnalytics][alias-discussion]. +**Do not define both parameters,** otherwise this can result in [unexpected +behavior][]. For details, see [Is services.googleAnalytics.id an alias for +googleAnalytics][alias-discussion]. - [alias-discussion]: https://discourse.gohugo.io/t/config-is-services-googleanalytics-id-an-alias-for-googleanalytics/39469 - [unexpected behavior]: https://github.com/google/docsy/issues/921 - [v0.120.0]: https://github.com/gohugoio/hugo/releases/tag/v0.120.0 +[alias-discussion]: + https://discourse.gohugo.io/t/config-is-services-googleanalytics-id-an-alias-for-googleanalytics/39469 +[unexpected behavior]: https://github.com/google/docsy/issues/921 +[v0.120.0]: https://github.com/gohugoio/hugo/releases/tag/v0.120.0 {{% /alert %}} {{% alert title="Production-only feature!" color="primary" %}} - Analytics are enabled _only_ for **production** builds (called "environments" - in Hugo terminology). For information about Hugo environments and how to set - them, see the following [discussion][]. +Analytics are enabled _only_ for **production** builds (called "environments" in +Hugo terminology). For information about Hugo environments and how to set them, +see the following [discussion][]. - [discussion]: https://discourse.gohugo.io/t/what-does-setting-hugo-env-to-production-do/24669/2 +[discussion]: + https://discourse.gohugo.io/t/what-does-setting-hugo-env-to-production-do/24669/2 {{% /alert %}} @@ -146,6 +125,7 @@ case where analytics is configured outside of Docsy. {{% /alert %}} + 1. Open your project's Hugo configuration file. 2. Set the response text that users see after clicking **Yes** or **No**. @@ -186,6 +166,7 @@ params: {{< /tab >}} {{< /tabpane >}} + 3. Save the edits to your configuration file. @@ -199,8 +180,8 @@ Page feedback is reported to Google Analytics through [events]. {{% alert title="Version note" color=warning %}} -As of Docsy version [0.8.0], page feedback is reported as custom `page_helpful` events, -rather than `click` events. +As of Docsy version [0.8.0], page feedback is reported as custom `page_helpful` +events, rather than `click` events. [0.8.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#080 @@ -226,6 +207,7 @@ visualize individual data points (per page) along with average values. Add the parameter `hide_feedback` to the page's front matter and set it to `true`. + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -244,12 +226,14 @@ hide_feedback: true } {{< /tab >}} {{< /tabpane >}} + ### Disable feedback on all pages Set `params.ui.feedback.enable` to `false` in `hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -274,6 +258,7 @@ params: } {{< /tab >}} {{< /tabpane >}} + ## Add a contact form with Fabform @@ -284,9 +269,9 @@ form that collects the user's email address to your site source: ```html
- - - + + +
``` @@ -305,26 +290,27 @@ using the `description` meta tag to tell search engines what your page is about. For each generated page, Docsy will set the content of the meta `description` by using the first of the following that is defined: -- The page `description` [frontmatter field]({{< ref -"content#page-frontmatter" >}}) +- The page `description` [frontmatter field](content/#page-frontmatter) - For non-index pages, the page [summary][], as computed by Hugo - The site description taken from the [site `params`][] -For the template code used to perform this computation, see -[layouts/partials/page-description.html][]. +For the code used to perform this computation, see [page-description.html]. Add more meta tags as needed to your project's copy of the `head-end.html` -partial. For details, see [Customizing templates]({{< ref "lookandfeel#customizing-templates" ->}}). +partial. For details, see +[Customizing templates](lookandfeel/#customizing-templates). -[Configure Google Analytics]: https://gohugo.io/templates/internal/#configure-google-analytics +[Configure Google Analytics]: + https://gohugo.io/templates/embedded/#configure-google-analytics [ga4-intro]: https://support.google.com/analytics/answer/1042508 [Google Analytics]: https://analytics.google.com/analytics/web/ [gtag.js]: https://support.google.com/analytics/answer/10220869 -[hugo-ga]: https://gohugo.io/templates/internal/#google-analytics -[internal templates]: https://gohugo.io/templates/internal/ -[layouts/partials/page-description.html]: https://github.com/google/docsy/blob/main/layouts/partials/page-description.html +[hugo-ga]: https://gohugo.io/templates/embedded/#google-analytics +[embedded templates]: https://gohugo.io/templates/embedded/ +[page-description.html]: + https://github.com/google/docsy/blob/main/layouts/_partials/page-description.html [site `params`]: https://gohugo.io/variables/site/#the-siteparams-variable [summary]: https://gohugo.io/content-management/summaries/ [configure]: #setup-1 -[configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file +[configuration file]: + https://gohugo.io/getting-started/configuration/#configuration-file diff --git a/userguide/content/en/docs/adding-content/iconsimages.md b/userguide/content/en/docs/adding-content/iconsimages.md index 8feed7501e..ca1e1ca94e 100644 --- a/userguide/content/en/docs/adding-content/iconsimages.md +++ b/userguide/content/en/docs/adding-content/iconsimages.md @@ -11,9 +11,10 @@ By default, Docsy shows a site logo at the start of the navbar, that is, at the extreme left. Place your project's SVG logo in `assets/icons/logo.svg`. This overrides the default Docsy logo in the theme. -If you don't want a logo to appear in the navbar, then set site parameter `navbar_logo` -to `false` in your project's config: +If you don't want a logo to appear in the navbar, then set site parameter +`navbar_logo` to `false` in your project's config: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -36,33 +37,59 @@ params: } {{< /tab >}} {{< /tabpane >}} + For information about styling your logo, see [Styling your project logo and name][]. -[Styling your project logo and name]: /docs/adding-content/lookandfeel/#styling-your-project-logo-and-name +[Styling your project logo and name]: + /docs/adding-content/lookandfeel/#styling-your-project-logo-and-name ## Use icons -Docsy includes the free FontAwesome icons by default, including logos for sites like GitHub and Stack Overflow. You can view all available icons in the [FontAwesome documentation](https://fontawesome.com/icons/), including the FontAwesome version when the icon was added and whether it is available for free tier users. Check Docsy's [`package.json`](https://github.com/google/docsy/blob/main/package.json) and release notes for Docsy's currently included version of FontAwesome. +Docsy includes the free FontAwesome icons by default, including logos for sites +like GitHub and Stack Overflow. You can view all available icons in the +[FontAwesome documentation](https://fontawesome.com/icons/), including the +FontAwesome version when the icon was added and whether it is available for free +tier users. Check Docsy's +[`package.json`](https://github.com/google/docsy/blob/main/package.json) and +release notes for Docsy's currently included version of FontAwesome. -You can add FontAwesome icons to your [top-level menu](/docs/adding-content/navigation/#adding-icons-to-the-top-level-menu), [section menu](/docs/adding-content/navigation/#add-icons-to-the-section-menu), or anywhere in your text. +You can add FontAwesome icons to your +[top-level menu](/docs/adding-content/navigation/#adding-icons-to-the-top-level-menu), +[section menu](/docs/adding-content/navigation/#add-icons-to-the-section-menu), +or anywhere in your text. ## Add your favicons -The easiest way to do this is to create a set of favicons via http://cthedot.de/icongen (which lets you create a huge range of icon sizes and options from a single image) and/or [https://favicon.io](https://favicon.io), and put them in your site project's `static/favicons` directory. This will override the default favicons from the theme. +The easiest way to do this is to create a set of favicons via +https://cthedot.de/icongen (which lets you create a huge range of icon sizes and +options from a single image) and/or [https://favicon.io](https://favicon.io), +and put them in your site project's `static/favicons` directory. This will +override the default favicons from the theme. -Note that https://favicon.io doesn't create as wide a range of sizes as Icongen but *does* let you quickly create favicons from text: if you want to create text favicons you can use this site to generate them, then use Icongen to create more sizes (if necessary) from your generated `.png` file. +Note that https://favicon.io doesn't create as wide a range of sizes as Icongen +but _does_ let you quickly create favicons from text: if you want to create text +favicons you can use this site to generate them, then use Icongen to create more +sizes (if necessary) from your generated `.png` file. -If you have special favicon requirements, you can create your own `layouts/partials/favicons.html` with your links. +If you have special favicon requirements, you can create your own +`layouts/_partials/favicons.html` with your links. ## Add images ### Landing pages -Docsy's [`blocks/cover` shortcode](/docs/adding-content/shortcodes/#blockscover) make it easy to add large cover images to your landing pages. The shortcode looks for an image with the word "background" in the name inside the landing page's [Page Bundle](https://gohugo.io/content-management/page-bundles/) - so, for example, if you've copied the example site, the landing page image in `content/en/_index.html` is `content/en/featured-background.jpg`. +Docsy's [`blocks/cover` shortcode](/docs/adding-content/shortcodes/#blockscover) +make it easy to add large cover images to your landing pages. The shortcode +looks for an image with the word "background" in the name inside the landing +page's [Page Bundle](https://gohugo.io/content-management/page-bundles/) - so, +for example, if you've copied the example site, the landing page image in +`content/en/_index.html` is `content/en/featured-background.jpg`. -You specify the preferred display height of a cover block container (and hence its image) using the block's `height` parameter. For a full viewport height, use `full`: +You specify the preferred display height of a cover block container (and hence +its image) using the block's `height` parameter. For a full viewport height, use +`full`: ```html {{}} @@ -70,7 +97,8 @@ You specify the preferred display height of a cover block container (and hence i {{}} ``` -For a shorter image, as in the example site's About page, use one of `min`, `med`, `max` or `auto` (the actual height of the image): +For a shorter image, as in the example site's About page, use one of `min`, +`med`, `max` or `auto` (the actual height of the image): ```html {{}} @@ -80,9 +108,9 @@ For a shorter image, as in the example site's About page, use one of `min`, `med ### Other pages -To add inline images to other pages, use the [`imgproc` shortcode](/docs/adding-content/shortcodes/#imgproc). Alternatively, if you prefer, just use regular Markdown or HTML images and add your image files to your project's `static` directory. You can find out more about using this directory in [Adding static content](/docs/adding-content/content/#adding-static-content). - -## Images used on this site - -Images used as background images in this site are in the [public domain](https://commons.wikimedia.org/wiki/User:Bep/gallery#Wed_Aug_01_16:16:51_CEST_2018) and can be used freely. The porridge image in the example site is by iha31 from Pixabay. - +To add inline images to other pages, use the +[`imgproc` shortcode](/docs/adding-content/shortcodes/#imgproc). Alternatively, +if you prefer, just use regular Markdown or HTML images and add your image files +to your project's `static` directory. You can find out more about using this +directory in +[Adding static content](/docs/adding-content/content/#adding-static-content). diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index 21ad83a401..53561eaa46 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -3,7 +3,8 @@ title: Look and Feel date: 2017-01-05 weight: 2 description: Customize colors, fonts, code highlighting, and more for your site. -spelling: cSpell:ignore wordmark docsy +# prettier-ignore +cSpell:ignore: anotherclass autoprefixing baseof blockscover docsy lightdark monokai myclass onedark wordmark --- By default, a site using Docsy has the theme's default fonts, colors, and @@ -31,8 +32,8 @@ place them inside your project's `assets/scss/` folder: Use these files to add project-specific definitions of theme variables as well as any additional Bootstrap variables you want to set or override. For - details, including an explanation of which file to use, see [Site - colors](#site-colors). + details, including an explanation of which file to use, see + [Site colors](#site-colors). For a list of Docsy's theme variables and their default values, see [`_variables.scss`]. For information about other Bootstrap 5 variables, see @@ -41,17 +42,27 @@ place them inside your project's `assets/scss/` folder: - **[`_styles_project.scss`]** is where you can add your own custom SCSS styles, including overriding any of the styles in Docsy's theme SCSS files. -[`_styles_project.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss -[`_variables.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss -[`_variables_project.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss -[`_variables_project_after_bs.scss`]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project_after_bs.scss +[`_styles_project.scss`]: + https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss +[`_variables.scss`]: + https://github.com/google/docsy/blob/main/assets/scss/_variables.scss +[`_variables_project.scss`]: + https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss +[`_variables_project_after_bs.scss`]: + https://github.com/google/docsy/blob/main/assets/scss/_variables_project_after_bs.scss [bs_var]: https://github.com/twbs/bootstrap/blob/v5.3.3/scss/_variables.scss {{% alert title="Tip" %}} -PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in server mode (it is a little slow), so Chrome is the recommended choice for development. + +PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in +server mode (it is a little slow), so Chrome is the recommended choice for +development. + {{% /alert %}} -## Site colors +## Colors and color themes + +### Site colors To customize your site's colors, add SCSS variable overrides to **`assets/scss/_variables_project.scss`**. For example, you can set the primary @@ -59,20 +70,21 @@ and secondary site colors as follows: ```scss $primary: #390040; -$secondary: #A23B72; +$secondary: #a23b72; ``` -The theme has features such as gradient backgrounds (`$enable-gradients`) and -shadows (`$enable-shadows`) enabled by default. These can also be toggled in -your project variables file by setting the variables to `false`. +Docsy has [Bootstrap][bs-docs] features such as gradient backgrounds +(`$enable-gradients`) and shadows (`$enable-shadows`) enabled by default. These +can also be toggled in your project variables file by setting the variables to +`false`. To add colors to or modify Bootstrap's [color maps], use **`assets/scss/_variables_project_after_bs.scss`**. For example: ```scss $custom-colors: ( - "my-favorite-color": purple, - "my-other-color": pink + 'my-favorite-color': purple, + 'my-other-color': pink, ); $theme-colors: map-merge($theme-colors, $custom-colors); @@ -80,14 +92,48 @@ $theme-colors: map-merge($theme-colors, $custom-colors); Learn how to modify maps, see [Maps and loops] and [Adding theme colors]. -[Adding theme colors]: https://getbootstrap.com/docs/5.3/customize/color-modes/#adding-theme-colors +[Adding theme colors]: + https://getbootstrap.com/docs/5.3/customize/color-modes/#adding-theme-colors [color maps]: https://getbootstrap.com/docs/5.3/customize/color/#color-sass-maps -[Maps and loops]: https://getbootstrap.com/docs/5.3/customize/sass/#maps-and-loops -[variable defaults]: https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults +[Maps and loops]: + https://getbootstrap.com/docs/5.3/customize/sass/#maps-and-loops +[variable defaults]: + https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults + +### Light/dark color themes + +Docsy 0.10.0 supports light and [dark mode] color themes. To allow your website +users to choose light/dark modes, **enable the Docsy [light/dark menu]** or +create your own custom theme selector. + +If your site uses [Chroma for code highlighting], there are extra steps required +so that code-block styles are compatible with light/dark mode: + +- Ensure that `markup.highlight.noClasses` is `false` in your project config. + For details about this option, see [Generate syntax highlighter CSS]. +- Add `@import 'td/code-dark'` to your project's [`_styles_project.scss`] file. + +For details, see [Chroma for code highlighting]. + +{{% alert title="Note" %}} + +Light/dark color themes, only affect documentation pages, and white [blocks +shortcodes]. + +[blocks shortcodes]: shortcodes/#shortcode-blocks + +{{% /alert %}} + +[Chroma for code highlighting]: #code-highlighting-with-chroma +[light/dark menu]: #lightdark-mode-menu +[Generate syntax highlighter CSS]: + https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css ## Fonts -The theme uses [Open Sans](https://fonts.google.com/specimen/Open+Sans) as its primary font. To disable Google Fonts and use a system font, set this SCSS variable in `assets/scss/_variables_project.scss`: +The theme uses [Open Sans](https://fonts.google.com/specimen/Open+Sans) as its +primary font. To disable Google Fonts and use a system font, set this SCSS +variable in `assets/scss/_variables_project.scss`: ```scss $td-enable-google-fonts: false; @@ -96,72 +142,80 @@ $td-enable-google-fonts: false; To configure another Google Font: ```scss -$google_font_name: "Open Sans"; -$google_font_family: "Open+Sans:300,300i,400,400i,700,700i"; +$google_font_name: 'Open Sans'; +$google_font_family: 'Open+Sans:300,300i,400,400i,700,700i'; ``` -Note that if you decide to go with a font with different weights (in the built-in configuration this is `300` (light), `400` (medium) and `700` (bold)), you also need to adjust the weight related variables, i.e. variables starting with `$font-weight-`. +Note that if you decide to go with a font with different weights (in the +built-in configuration this is `300` (light), `400` (medium) and `700` (bold)), +you also need to adjust the weight related variables, i.e. variables starting +with `$font-weight-`. ## CSS utilities -For documentation of available CSS utility classes, see the [Bootstrap Documentation](https://getbootstrap.com/). This theme adds very little on its own in this area. However, we have added some color state CSS classes that can be useful in a dynamic context: +For documentation of available CSS utility classes, see the [Bootstrap +documentation][bs-docs]. This theme adds very little on its own in this area. +However, we have added some color state CSS classes that can be useful in a +dynamic context: -* `.-bg-` -* `.-text-` +- `.-bg-` +- `.-text-` -You can use these classes, for example, to style your text in an appropriate color when you don't know if the `primary` color is dark or light, to ensure proper color contrast. They are also useful when you receive the color code as a [shortcode](/docs/adding-content/shortcodes/) parameter. +You can use these classes, for example, to style your text in an appropriate +color when you don't know if the `primary` color is dark or light, to ensure +proper color contrast. They are also useful when you receive the color code as a +[shortcode](/docs/adding-content/shortcodes/) parameter. -The value of `` can be any of the color names, `primary`, `white`, `dark`, `warning`, `light`, `success`, `300`, `blue`, `orange` etc. +The value of `` can be any of the color names, `primary`, `white`, +`dark`, `warning`, `light`, `success`, `300`, `blue`, `orange` etc. -When you use `.-bg-`, the text colors will be adjusted to get proper contrast: +When you use `.-bg-`, the text colors will be adjusted to get proper +contrast: ```html -
Background: Primary
-
Background: Gray 200
+
Background: Primary
+
Background: Gray 200
``` -
Background: Primary
-
Background: Gray 200
+
Background: Primary
+
Background: Gray 200
-`.-text-` sets the text color only: +To only set the text color use `.-text-`: ```html -
Text: Blue
+
Text: Blue
``` -
Text: Blue
+
Text: Blue
## Code highlighting with Chroma -With Hugo version 0.60 and higher, you can choose from a range of code block highlight and colour styles using [Chroma](https://github.com/alecthomas/chroma) that are applied to your fenced code blocks by default. If you copied a recent `hugo.toml` your site uses Tango (like this site), otherwise the Hugo default is Monokai. You can switch to any of the [available Chroma styles](https://xyproto.github.io/splash/docs/all.html) (including our Docsy default Tango) using your `hugo.toml`/`hugo.yaml`/`hugo.json`: +As of Hugo 0.60+, you can choose from a range of code block highlight and color +styles using [Chroma](https://github.com/alecthomas/chroma). These styles are +applied to your fenced code blocks. For details about code highlighting in Hugo +using Chroma, see [Syntax Highlighting]. +### Chroma style configuration + +Hugo's default Chroma style is [monokai]. To use another style, such as [tango], +add the following to your project configuration: + + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [markup] - [markup.goldmark] - [markup.goldmark.renderer] - unsafe = true [markup.highlight] - # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html style = "tango" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} markup: - goldmark: - renderer: - unsafe: true highlight: style: tango {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { "markup": { - "goldmark": { - "renderer": { - "unsafe": true - } - }, "highlight": { "style": "tango" } @@ -169,39 +223,60 @@ markup: } {{< /tab >}} {{< /tabpane >}} + -By default code highlighting styles are not applied to code blocks without a specified language, instead you get Docsy's default style of grey with black text. If you would like the code highlighting style to apply to all code blocks, even without a language, uncomment or add the following line under `[markup.highlight]` in your `hugo.toml`/`hugo.yaml`/`hugo.json`. +For the complete list of available styles, see [Chroma Style Gallery]. -{{< tabpane >}} -{{< tab header="Configuration file:" disabled=true />}} -{{< tab header="hugo.toml" lang="toml" >}} -# Uncomment if you want your chosen highlight style used for code blocks without a specified language -guessSyntax = true -{{< /tab >}} -{{< tab header="hugo.yaml" lang="yaml" >}} -guessSyntax: true -{{< /tab >}} -{{< tab header="hugo.json" lang="json" >}} -"guessSyntax": true -{{< /tab >}} -{{< /tabpane >}} +[Chroma Style Gallery]: https://xyproto.github.io/splash/docs/ +[monokai]: https://xyproto.github.io/splash/docs/monokai.html +[onedark]: https://xyproto.github.io/splash/docs/onedark.html +[Syntax Highlighting]: https://gohugo.io/content-management/syntax-highlighting/ +[tango]: https://xyproto.github.io/splash/docs/tango.html + +### Light/dark code styles + +Docsy's default Chroma styles for [light/dark mode] are: + +- [tango] for light mode +- [onedark] for dark mode -If you are using a Docsy version later than `0.6.0`, the code blocks show a -"Copy to clipboard" icon in the top right-hand corner. To disable this -functionality set `disable_click2copy_chroma` to `true` in your configuration -file: +If you would like to use other styles, save the [Hugo generated Chroma styles] +to the appropriate file: -You can find out more about code highlighting in Hugo with Chroma in [Syntax Highlighting](https://gohugo.io/content-management/syntax-highlighting/). +- [assets/scss/td/chroma/_light.scss] +- [assets/scss/td/chroma/_dark.scss] + +[assets/scss/td/chroma/_dark.scss]: + https://github.com/google/docsy/blob/main/assets/scss/td/chroma/_dark.scss +[assets/scss/td/chroma/_light.scss]: + https://github.com/google/docsy/blob/main/assets/scss/td/chroma/_light.scss +[Hugo generated Chroma styles]: + https://gohugo.io/commands/hugo_gen_chromastyles/ +[light/dark mode]: #lightdark-color-themes + +### Code blocks without a specified language + +By default, highlighting is not applied to code blocks without a specified +language. If you would like code highlighting to apply to _all_ code blocks, +even without a language, set `markup.highlight.guessSyntax` to `true` in your +project's configuration file. + +### Copy to clipboard + +If you are using a Docsy 0.6.0 or later, code blocks show a "Copy to clipboard" +button in the top right-hand corner. To disable this functionality, set +`disable_click2copy_chroma` to `true` in your configuration file: ## Code highlighting with Prism -Optionally, you can enable Prism syntax highlighting in your `hugo.toml`/`hugo.yaml`/`hugo.json`: +Optionally, you can enable Prism syntax highlighting in your +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params] -# Enable syntax highlighting and copy buttons on code blocks with Prism prism_syntax_highlighting = true {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} @@ -216,32 +291,46 @@ params: } {{< /tab >}} {{< /tabpane >}} + -When this option is enabled your site uses [Prism](https://prismjs.com/index.html) instead of Chroma for code block highlighting. +When this option is enabled your site uses +[Prism](https://prismjs.com/index.html) instead of Chroma for code block +highlighting. -Prism is a popular open source syntax highlighter which supports over 200 [languages](https://prismjs.com/index.html#supported-languages) and various [plugins](https://prismjs.com/index.html#plugins). +Prism is a popular open source syntax highlighter which supports over 200 +[languages](https://prismjs.com/index.html#supported-languages) and various +[plugins](https://prismjs.com/index.html#plugins). -Docsy includes JavaScript and CSS files for a basic Prism configuration, which supports: +Docsy includes JavaScript and CSS files for a basic Prism configuration, which +supports: -* Code blocks styled with the Prism `Default` theme -* Copy to clipboard buttons on code blocks -* Syntax highlighting for a number of common languages, as specified in the following Prism download link, [Customize your download][prismjs-download+]. +- Code blocks styled with the Prism `Default` theme +- Copy to clipboard buttons on code blocks +- Syntax highlighting for a number of common languages, as specified in the + following Prism download link, [Customize your download][prismjs-download+]. -[prismjs-download+]: https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+scss+sql+toml+yaml&plugins=toolbar+copy-to-clipboard +[prismjs-download+]: + https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+scss+sql+toml+yaml&plugins=toolbar+copy-to-clipboard ### Code blocks with no language -By default, Prism code highlighting styles are not applied to code blocks without a specified language, instead you get Docsy's default style of grey with black text. To apply Prism styling to code blocks with no language or a language not supported by Prism, specify `none` as the language after your triple backticks. +By default, Prism code highlighting styles are not applied to code blocks +without a specified language, instead you get Docsy's default style of grey with +black text. To apply Prism styling to code blocks with no language or a language +not supported by Prism, specify `none` as the language after your triple +backticks. ### Extending Prism for additional languages or plugins -If the included Prism configuration is not sufficient for your requirements, and you want to use additional languages or plugins you can replace the included files with your own. +If the included Prism configuration is not sufficient for your requirements, and +you want to use additional languages or plugins you can replace the included +files with your own. -1. Download your own Prism JS and CSS files from +1. Download your own Prism JS and CSS files from + 2. Replace the included Prism JS and CSS with the files you downloaded: - * Copy the Javascript file to `static/js/prism.js` - * Copy the CSS file to `static/css/prism.css` - + - Copy the Javascript file to `static/js/prism.js` + - Copy the CSS file to `static/css/prism.css` ## Navbar @@ -255,9 +344,10 @@ of the following: To ensure your logo displays correctly, you may want to resize it and ensure that it doesn't have height and width attributes so that its size is fully - responsive. [Override the default styling][project-styles] of `.td-navbar - .navbar-brand svg` or (equivalently) `.td-navbar .navbar-brand__logo` as - needed. + responsive. [Override the default styling][project-styles] of + `.td-navbar .navbar-brand svg` or (equivalently) + `.td-navbar .navbar-brand__logo` as needed. + 2. Your project name, which is the site `title`. If you don't want your project name to appear (for example, because your logo is or contains a [wordmark][]), then add the following custom styling to your [project's @@ -274,18 +364,19 @@ of the following: [wordmark]: https://en.wikipedia.org/wiki/Wordmark [your logo]: /docs/adding-content/iconsimages/#add-your-logo -### Light/Dark mode menu +### Light/dark mode menu If you enable this feature, Docsy adds a menu to your navbar that lets users switch your site's documentation page display between a default "light" mode, and a "dark" mode where the text is displayed in a light color on a dark background. -To enable the display of a Light/[Dark mode] menu in the navbar, set +To enable the display of a light/[dark mode] menu in the navbar, set `params.ui.showLightDarkModeMenu` to `true` in your project's configuration file. The dropdown menu appears at the right, immediately before the [search box], if present. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -308,6 +399,7 @@ params: } {{< /tab >}} {{< /tabpane >}} + [dark mode]: https://getbootstrap.com/docs/5.3/customize/color-modes/#dark-mode [search box]: /docs/adding-content/search/ @@ -329,7 +421,8 @@ site's [configuration file][]. [About Docsy]: https://www.docsy.dev/about/ [blocks/cover]: /docs/adding-content/shortcodes/#blockscover -[configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file +[configuration file]: + https://gohugo.io/getting-started/configuration/#configuration-file [primary color]: #site-colors ## Tables @@ -343,8 +436,9 @@ Docsy applies the following styles to all tables, through the class `.td-table`: - `display: block`, which is necessary for tables to be responsive. This styling configuration gives you responsive tables using Markdown only, -without the need to wrap the table in a `
`. It does, however, mean that all your tables have `display` -set to `block`. If you don't want this, you can create your own custom styles for tables. +without the need to wrap the table in a `
`. It does, however, mean that all +your tables have `display` set to `block`. If you don't want this, you can +create your own custom styles for tables. {{% alert title="Note" %}} @@ -353,7 +447,8 @@ tables][wrap-tables] with `.table-responsive` — however, we think letting users create responsive tables with just Markdown table syntax is more convenient. -[wrap-tables]: https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables +[wrap-tables]: + https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables {{% /alert %}} @@ -362,6 +457,7 @@ table. From the resulting `` style base, it is easier to apply your own custom styles (rather than trying to undo Docsy table styling), as is illustrated in the following example: + ```markdown | Shape | Number of sides | | -------- | --------------- | @@ -370,13 +466,16 @@ illustrated in the following example: {.td-initial .my-dark-table-style} ``` -The example above uses [Markdown attribute][] syntax, and might render like this: +The example above uses [Markdown attribute][] syntax, and might render like +this: + | Shape | Number of sides | | -------- | --------------- | | Triangle | 3 | | Square | 4 | {.td-initial .table .table-dark} + [Bootstrap table]: https://getbootstrap.com/docs/5.3/content/tables/ [Markdown attribute]: https://discourse.gohugo.io/t/markdown-attributes/41783 @@ -385,25 +484,34 @@ The example above uses [Markdown attribute][] syntax, and might render like this ### Add code to head or before body end -If you need to add some code (CSS import, cookie consent, or similar) to the `head` section on every page, add the `head-end.html` partial to your project: - -``` -layouts/partials/hooks/head-end.html -``` - -And add the code you need in that file. Your partial code is automatically included just before the end of the theme partial [`head.html`](https://github.com/google/docsy/blob/main/layouts/partials/head.html). The theme version of [`head-end.html`](https://github.com/google/docsy/blob/main/layouts/partials/hooks/head-end.html) is empty. - - -Similarly, if you want to add some code right before the `body` end, create your own version of the following file: - -``` -layouts/partials/hooks/body-end.html -``` - -Any code in this file is included automatically at the end of the theme partial [`scripts.html`](https://github.com/google/docsy/blob/main/layouts/partials/head.html). - -Both `head.html` and `scripts.html` are then used to build Docsy's [base page layout](https://github.com/google/docsy/blob/main/layouts/_default/baseof.html), which is used by all the other page templates: - +If you need to add some code (CSS import, cookie consent, or similar) to the +`head` section on every page, add a [hooks/head-end.html] partial to your +project (the theme version is an empty placeholder). The content of this partial +is automatically included just before the end of the theme partial [head.html]. + +Similarly, if you want to add some code right before the `body` end, create your +own version of [hooks/body-end.html]. This partial is included automatically at +the end of the theme partial [scripts.html]. + +Both [head.html] and [scripts.html] are included from [baseof.html], Docsy's +[base template][]. + +[baseof.html]: https://github.com/google/docsy/blob/main/layouts/baseof.html +[base template]: https://gohugo.io/templates/base/ +[head.html]: + https://github.com/google/docsy/blob/main/layouts/_partials/head.html +[hooks/body-end.html]: + https://github.com/google/docsy/blob/main/layouts/_partials/hooks/body-end.html +[hooks/head-end.html]: + https://github.com/google/docsy/blob/main/layouts/_partials/hooks/head-end.html +[scripts.html]: + https://github.com/google/docsy/blob/main/layouts/_partials/head.html + +Both `head.html` and `scripts.html` are then used to build Docsy's +[base page layout](https://github.com/google/docsy/blob/main/layouts/_default/baseof.html), +which is used by all the other page templates: + + ```html @@ -424,3 +532,78 @@ Both `head.html` and `scripts.html` are then used to build Docsy's [base page la ``` + +### Adding a banner before page content (EXPERIMENTAL) {#before-page-content} + +To have a banner or other similar content appear at the top of the pages in a +section, add the relevant HTML to a [_td-content-after-header.html] file in the +section's page path under `layouts` -- such as +`layouts/blog/_td-content-after-header.html`. Add the file directly under +`layouts` to have the file processed for all docs, blog, and swagger pages. The +file's content will be included inside the `div.td-content` after ``, +just before `.Content` is rendered. + +[_td-content-after-header.html]: + https://github.com/google/docsy/blob/main/layouts/_td-content-after-header.html + +## Adding custom class to the body element + +By default, Docsy adds the `td-{{ .Kind }}` class, where the kind is the kind of +the page, like section, blog, and so on. For example: + + +```html + +``` + +Sometimes it's useful to assign custom classes to a page, or to an entire +section, for example, to apply custom styling. To do so, add the `body_class` +parameter to the front matter of your page. The value of the parameter will then +be added to the class attribute of your page's body element. + +To add the classes `myclass` and `anotherclass`, add the following line to the +front matter of the page: + +```yaml +body_class: myclass anotherclass +``` + +The page's opening body tag will look like this (assuming it is a section page): + + +```html + +``` + +To apply the custom class to every page of a section or a directory, use the +[Front Matter Cascade](https://gohugo.io/content-management/front-matter/#front-matter-cascade) +feature of Hugo in your configuration file, or in the front matter of the +highest-level page you want to modify. + +[bs-docs]: https://getbootstrap.com/docs/ + +## Sidebar table of contents + +By default, Docsy shows the table of contents for the current page in the right sidebar using the built-in function of Hugo. You can replace that with a JavaScript-based ToC that uses the [https://tscanlin.github.io/tocbot/](Tocbot library) by setting the following in your `config.toml` file: + +```toml +[params.jstoc] +enable = true +``` + +By default, h2-h4 headings are included in the sidebar, which includes tips and warnings if you are using the [alert shortcode of Docsy](/docs/adding-content/shortcodes/#alert). To change that, +provide a comma-separated list of the headings to include in the `custom_headings` parameter, for example: + +```toml +[params.jstoc] +enable = true +custom_headings = "h2, h3" +``` + +Compared to the default sidebar ToC, this solution: + +- has a marker that shows the current location of the screen (useful for long pages) +- shows the correct title even if the title contains a shortcode +- shows the title in the toc even if it was included from another file + +![Screenshot of JavaScript-based sidebar table of contents](/images/sidebar-toc-with-tocbot.png) diff --git a/userguide/content/en/docs/adding-content/navigation.md b/userguide/content/en/docs/adding-content/navigation.md index 9bb7fc8e4e..cda7ea0f53 100644 --- a/userguide/content/en/docs/adding-content/navigation.md +++ b/userguide/content/en/docs/adding-content/navigation.md @@ -5,14 +5,26 @@ weight: 3 description: Customize site navigation for your Docsy site. --- -Docsy provides multiple built-in navigation features for your sites, including site menus, section menus, and page menus. This page shows you how they work and how to configure and customize them to meet your needs. +Docsy provides multiple built-in navigation features for your sites, including +site menus, section menus, and page menus. This page shows you how they work and +how to configure and customize them to meet your needs. ## Top-level menu -The top level menu (the one that appears in the top navigation bar for the entire site) uses your site's [`main` menu](https://gohugo.io/content-management/menus/). All Hugo sites have a `main` menu array of menu entries, accessible via the `.Site.Menus` site variable and populatable via page front matter or your site's `hugo.toml`/`hugo.yaml`/`hugo.json`. +The top level menu (the one that appears in the top navigation bar for the +entire site) uses your site's +[`main` menu](https://gohugo.io/content-management/menus/). All Hugo sites have +a `main` menu array of menu entries, accessible via the `.Site.Menus` site +variable and populatable via page front matter or your site's +`hugo.toml`/`hugo.yaml`/`hugo.json`. -To add a page or section to this menu, add it to the site's `main` menu in either `hugo.toml`/`hugo.yaml`/`hugo.json` or in the destination page's front matter (in `_index.md` or `_index.html` for a section, as that's the section landing page). For example, here's how we added the Documentation section landing page to the main menu in this site: +To add a page or section to this menu, add it to the site's `main` menu in +either `hugo.toml`/`hugo.yaml`/`hugo.json` or in the destination page's front +matter (in `_index.md` or `_index.html` for a section, as that's the section +landing page). For example, here's how we added the Documentation section +landing page to the main menu in this site: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -48,11 +60,16 @@ menu: } {{< /tab >}} {{< /tabpane >}} + -The menu is ordered from left to right by page `weight`. So, for example, a section index or page with `weight: 30` would appear after the Documentation section in the menu, while one with `weight: 10` would appear before it. +The menu is ordered from left to right by page `weight`. So, for example, a +section index or page with `weight: 30` would appear after the Documentation +section in the menu, while one with `weight: 10` would appear before it. -If you want to add a link to an external site to this menu, add it in `hugo.toml`/`hugo.yaml`/`hugo.json`, specifying the `weight`. +If you want to add a link to an external site to this menu, add it in +`hugo.toml`/`hugo.yaml`/`hugo.json`, specifying the `weight`. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -82,11 +99,19 @@ menu: } {{< /tab >}} {{< /tabpane >}} + ### Adding icons to the top-level menu -As described in the [Hugo docs](https://gohugo.io/content-management/menus/#add-non-content-entries-to-a-menu), you can add icons to the top-level menu by using the pre and/or post parameter for main menu items defined in your site's `hugo.toml`/`hugo.yaml`/`hugo.json` or via page front matter. For example, the following configuration adds the GitHub icon to the GitHub menu item, and a **New!** alert to indicate that this is a new addition to the menu. +As described in the +[Hugo docs](https://gohugo.io/content-management/menus/#add-non-content-entries-to-a-menu), +you can add icons to the top-level menu by using the pre and/or post parameter +for main menu items defined in your site's `hugo.toml`/`hugo.yaml`/`hugo.json` +or via page front matter. For example, the following configuration adds the +GitHub icon to the GitHub menu item, and a **New!** alert to indicate that this +is a new addition to the menu. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -122,8 +147,11 @@ menu: } {{< /tab >}} {{< /tabpane >}} + -You can find a complete list of icons to use in the [FontAwesome documentation](https://fontawesome.com/icons?d=gallery&p=2). Docsy includes the free FontAwesome icons by default. +You can find a complete list of icons to use in the +[FontAwesome documentation](https://fontawesome.com/icons?d=gallery&p=2). Docsy +includes the free FontAwesome icons by default. ### Adding a version drop-down @@ -135,15 +163,25 @@ You can find out more in the guide to ### Adding a language drop-down -If you configure more than one language in `hugo.toml`, the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language. +If you configure more than one language in `hugo.toml`, the Docsy theme adds a +language selector drop down to the top-level menu. Selecting a language takes +the user to the translated version of the current page, or the home page for the +given language. You can find out more in [Multi-language support](/docs/language/). ## Section menu -The section menu, as shown in the left side of the `docs` section, is automatically built from the `content` tree. Like the top-level menu, it is ordered by page or section index `weight` (or by page creation `date` if `weight` is not set), with the page or index's `Title`, or `linkTitle` if different, as its link title in the menu. If a section subfolder has pages other than `_index.md` or `_index.html`, those pages will appear as a submenu, again ordered by `weight`. For example, here's the metadata for this page showing its `weight` and `title`: - +The section menu, as shown in the left side of the `docs` section, is +automatically built from the `content` tree. Like the top-level menu, it is +ordered by page or section index `weight` (or by page creation `date` if +`weight` is not set), with the page or index's `Title`, or `linkTitle` if +different, as its link title in the menu. If a section subfolder has pages other +than `_index.md` or `_index.html`, those pages will appear as a submenu, again +ordered by `weight`. For example, here's the metadata for this page showing its +`weight` and `title`: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -177,11 +215,18 @@ description: > } {{< /tab >}} {{< /tabpane >}} + -To hide a page or section from the left navigation menu, set `toc_hide: true` in the front matter. +To hide a page or section from the left navigation menu, set `toc_hide: true` in +the front matter. -To hide a page from the section summary on a [docs section landing page]({{< ref "content#docs-section-landing-pages" >}}), set `hide_summary: true` in the front matter. If you want to hide a page from both the TOC menu and the section summary list, you need to set both `toc_hide` and `hide_summary` to `true` in the front matter. +To hide a page from the section summary on a [docs section landing +page]({{< ref "content#docs-section-landing-pages" >}}), set +`hide_summary: true` in the front matter. If you want to hide a page from both +the TOC menu and the section summary list, you need to set both `toc_hide` and +`hide_summary` to `true` in the front matter. + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -215,19 +260,39 @@ description: > } {{< /tab >}} {{< /tabpane >}} + ### Section menu options -By default, the section menu shows the current section fully expanded all the way down. This may make the left nav too long and difficult to scan for bigger sites. Try setting site parameter `ui.sidebar_menu_compact = true` in `hugo.toml`. +By default, the section menu shows the current section fully expanded all the +way down. This may make the left nav too long and difficult to scan for bigger +sites. Try setting site parameter `ui.sidebar_menu_compact = true` in +`hugo.toml`. + +With the compact menu (`.ui.sidebar_menu_compact = true`), only the current +page's ancestors, siblings and direct descendants are shown. You can use the +optional parameter `.ui.ul_show` to set a desired menu depth to always be +visible. For example, with `.ui.ul_show = 1` the first menu level is always +displayed. -With the compact menu (`.ui.sidebar_menu_compact = true`), only the current page's ancestors, siblings and direct descendants are shown. You can use the optional parameter `.ui.ul_show` to set a desired menu depth to always be visible. For example, with `.ui.ul_show = 1` the first menu level is always displayed. +The number of sidebar entries shown per section can be configured using the +`.ui.sidebar_menu_truncate` parameter (default: 100). -As well as the completely expanded and compact menu options, you can also create a foldable menu by setting the site parameter `ui.sidebar_menu_foldable = true` in `hugo.toml`. The foldable menu lets users expand and collapse menu sections by toggling arrow icons beside the section parents in the menu. +As well as the completely expanded and compact menu options, you can also create +a foldable menu by setting the site parameter `ui.sidebar_menu_foldable = true` +in `hugo.toml`. The foldable menu lets users expand and collapse menu sections +by toggling arrow icons beside the section parents in the menu. -On large sites (default: > 2000 pages) the section menu is not generated for each page, but cached for the whole section. The HTML classes for marking the active menu item (and menu path) are then set using JS. You can adjust the limit for activating the cached section menu with the optional parameter `.ui.sidebar_cache_limit`. +On large sites (default: > 2000 pages) the section menu is not generated for +each page, but cached for the whole section. The HTML classes for marking the +active menu item (and menu path) are then set using JS. You can adjust the limit +for activating the cached section menu with the optional parameter +`.ui.sidebar_cache_limit`. -The tabbed pane below lists the menu section options you can define in your project [configuration file]. +The tabbed pane below lists the menu section options you can define in your +project [configuration file]. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}}{{< tab header="hugo.toml" lang="toml" >}} [params.ui] @@ -257,36 +322,85 @@ params: } {{< /tab >}} {{< /tabpane >}} - + ### Add icons to the section menu -You can add icons to the section menu in the sidebar by setting the `icon` parameter in the page front matter (e.g. `icon: fa-solid fa-screwdriver-wrench`). +You can add icons to the section menu in the sidebar by setting the `icon` +parameter in the page front matter (e.g. +`icon: fa-solid fa-screwdriver-wrench`). -You can find a complete list of icons to use in the [FontAwesome documentation](https://fontawesome.com/icons?d=gallery&p=2). Docsy includes the free FontAwesome icons by default. +You can find a complete list of icons to use in the +[FontAwesome documentation](https://fontawesome.com/icons?d=gallery&p=2). Docsy +includes the free FontAwesome icons by default. -Out of the box, if you want to use icons, you should define icons for all items on the same menu level in order to ensure an appropriate look. If the icons are used in a different way, individual CSS adjustments are likely necessary. +Out of the box, if you want to use icons, you should define icons for all items +on the same menu level in order to ensure an appropriate look. If the icons are +used in a different way, individual CSS adjustments are likely necessary. ### Add manual links to the section menu -By default the section menu is entirely generated from your section's pages. If you want to add a manual link to this menu, such as a link to an external site or a page in a different section of your site, you can do this by creating a *placeholder page file* in the doc hierarchy with the appropriate weight and some special parameters in its metadata (frontmatter) to specify the link details. +By default the section menu is entirely generated from your section's pages. If +you want to add a manual link to this menu, such as a link to an external site +or a page in a different section of your site, you can do this by creating a +_placeholder page file_ in the doc hierarchy with the appropriate weight and +some special parameters in its metadata (frontmatter) to specify the link +details. + +To create a placeholder page, create a page file as usual in the directory where +you want the link to show up in the menu, and add a `manualLink` parameter to +its metadata. If a page has `manualLink` in its metadata, Docsy generates a link +for it in the section menu for this page and in the section index (the list of +the child pages of a section on a landing page - see +[description in the Docsy docs](/docs/adding-content/content/#docs-section-landing-pages)), +but the link destination is replaced by the value of `manualLink`. The link text +is the `title` (or `linkTitle` if set) of your placeholder page. You can +optionally also set the `title` attribute of the link with the parameter +`manualLinkTitle` and a link target with `manualLinkTarget` - for example if you +want an external link to open in a new tab you can set the link target to +`_blank`. Docsy automatically adds `rel=noopener` to links that open new tabs as +a security best practice. + +You can also use `manualLink` to add an additional cross reference to another +existing page of your site. For internal links you can choose to use the +parameter `manualLinkRelref` instead of `manualLink` to use the built-in Hugo +function +[relref](https://gohugo.io/functions/relref/ 'External link to official Hugo Docs'). +If `relref` can't find a unique page in your site, Hugo throws a error message. + +{{% alert title="Note" %}} Although all generated menu and landing page links +based on your placeholder file are set according to the parameters `manualLink` +or `manualLinkRelref`, Hugo still generates a regular HTML site page for the +file, albeit one with no generated links to it. To avoid confusion if users +accidentally land on a generated placeholder page, we recommend specifying the +URL for the external link in the normal content and / or page description of the +page. {{% /alert %}} -To create a placeholder page, create a page file as usual in the directory where you want the link to show up in the menu, and add a `manualLink` parameter to its metadata. If a page has `manualLink` in its metadata, Docsy generates a link for it in the section menu for this page and in the section index (the list of the child pages of a section on a landing page - see [description in the Docsy docs](/docs/adding-content/content/#docs-section-landing-pages)), but the link destination is replaced by the value of `manualLink`. The link text is the `title` (or `linkTitle` if set) of your placeholder page. You can optionally also set the `title` attribute of the link with the parameter `manualLinkTitle` and a link target with `manualLinkTarget` - for example if you want an external link to open in a new tab you can set the link target to `_blank`. Docsy automatically adds `rel=noopener` to links that open new tabs as a security best practice. - - You can also use `manualLink` to add an additional cross reference to another existing page of your site. For internal links you can choose to use the parameter `manualLinkRelref` instead of `manualLink` to use the built-in Hugo function [relref](https://gohugo.io/functions/relref/ "External link to official Hugo Docs"). If `relref` can't find a unique page in your site, Hugo throws a error message. +## Breadcrumb navigation - {{% alert title="Note" %}} - Although all generated menu and landing page links based on your placeholder file are set according to the parameters `manualLink` or `manualLinkRelref`, Hugo still generates a regular HTML site page for the file, albeit one with no generated links to it. To avoid confusion if users accidentally land on a generated placeholder page, we recommend specifying the URL for the external link in the normal content and / or page description of the page. - {{% /alert %}} +[Breadcrumb navigation] appears at the top of each non-index page be default. To +also display single-element breadcrumb lists in index pages, add the following +[style override] to your project: -## Breadcrumb navigation +```scss +.td-breadcrumbs__single { + display: inline !important; +} +``` -Breadcrumb navigation links appear at the top of each page by default. To disable breadcrumb navigation, set site param `ui.breadcrumb_disable = true` in `hugo.toml`. +[Breadcrumb navigation]: https://en.wikipedia.org/wiki/Breadcrumb_navigation +[style override]: /docs/adding-content/lookandfeel/#project-style-files -Breadcrumb navigation links are also shown for each item on the taxonomy results page (i.e. when you click one of the taxonomy labels, e.g. Tags/Categories). These breadcrumbs can be disabled in `hugo.toml` by setting site param `ui.taxonomy_breadcrumb_disable = true`. +Breadcrumb navigation is also shown for each item in the taxonomy results page +— that is, when you click one of the taxonomy labels such as _Categories_ +or _Tags_. -The tabbed pane below lists the breadcrumb navigation options you can define in your project [configuration file]. +As illustrated next, you can disable (non-taxonomy) breadcrumb navigation for an +entire project, by setting `ui.breadcrumb_disable` to true in your project +[configuration file]. Similarly, you can disabled taxonomy breadcrumbs by +setting `ui.taxonomy_breadcrumb_disable` to true: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}}{{< tab header="hugo.toml" lang="toml" >}} [params.ui] @@ -310,31 +424,45 @@ params: } {{< /tab >}} {{< /tabpane >}} + + +To disable breadcrumbs in a specific page or section set `ui.breadcrumb_disable` +to true in the page or section-index front matter. Here is an example of the +latter: + +```yaml +cascade: + params: + ui: + breadcrumb_disable: true +``` ## Heading self links Docsy supports build-time generation of heading self links using Hugo's `render-heading.html` [hook]. -To enable this feature in -your project, define `layouts/_default/_markup/render-heading.html` as: +To enable this feature in your project, define +`layouts/_markup/render-heading.html` as: ```go-html-template -{{ template "_default/_markup/td-render-heading.html" . }} +{{ partial "td/render-heading.html" . }} ``` The heading self-link anchor class is `.td-heading-self-link`, which you can -customize for your project. By default, the heading self-link style has these defaults: +customize for your project. By default, the heading self-link style has these +defaults: - The self-link symbol is `#`. - The symbol is always visible on mobile and touch devices, otherwise it is only visible on hover or focus. Your projects can also reuse (in your own custom heading render hook) or -override the heading self-link template -`_default/_markup/_td-heading-self-link.html`, which is defined in -[layouts/_default/_markup/td-render-heading.html]. +override the heading self-link partial `td/heading-self-link.html`, which is +defined in [layouts/_partials/td/render-heading.html]. -[layouts/_default/_markup/td-render-heading.html]: - https://github.com/google/docsy/tree/main/layouts/_default/_markup/td-render-heading.html +[configuration file]: + https://gohugo.io/getting-started/configuration/#configuration-file +[layouts/_partials/td/render-heading.html]: + https://github.com/google/docsy/tree/main/layouts/_partials/td/render-heading.html [hook]: https://gohugo.io/templates/render-hooks/ diff --git a/userguide/content/en/docs/adding-content/print.md b/userguide/content/en/docs/adding-content/print.md index f830fe91c1..1fdb45339d 100644 --- a/userguide/content/en/docs/adding-content/print.md +++ b/userguide/content/en/docs/adding-content/print.md @@ -1,17 +1,24 @@ --- -title: "Print Support" -linkTitle: "Print Support" -weight: 7 +title: 'Print Support' +linkTitle: 'Print Support' +weight: 7 description: > - Making it easier to print entire sections of documentation. + Making it easier to print entire sections of documentation. --- -Individual documentation pages print well from most browsers as the layouts have been styled to omit navigational chrome from the printed output. +Individual documentation pages print well from most browsers as the layouts have +been styled to omit navigational chrome from the printed output. -On some sites, it can be useful to enable a "print entire section" feature (as seen in this user guide). Selecting this option renders the entire current top-level section (such as Content and Customization for this page) with all of its child pages and sections in a format suited to printing, complete with a table of contents for the section. +On some sites, it can be useful to enable a "print entire section" feature (as +seen in this user guide). Selecting this option renders the entire current +top-level section (such as Content and Customization for this page) with all of +its child pages and sections in a format suited to printing, complete with a +table of contents for the section. -To enable this feature, add the "print" output format in your site's `hugo.toml`/`hugo.yaml`/`hugo.json` file for the "section" type: +To enable this feature, add the "print" output format in your site's +`hugo.toml`/`hugo.yaml`/`hugo.json` file for the "section" type: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -37,15 +44,20 @@ outputs: } {{< /tab >}} {{< /tabpane >}} + -The site should then show a "Print entire section" link in the right hand navigation. +The site should then show a "Print entire section" link in the right hand +navigation. ## Further Customization ### Disabling the ToC -To disable showing the the table of contents in the printable view, set the `disable_toc` param to `true`, either in the page front matter, or in `hugo.toml`/`hugo.yaml`/`hugo.json`: +To disable showing the the table of contents in the printable view, set the +`disable_toc` param to `true`, either in the page front matter, or in +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane langEqualsHeader=true >}} {{< tab header="Front matter:" disabled=true />}} {{< tab toml >}} @@ -70,7 +82,9 @@ disable_toc: true } {{< /tab >}} {{< /tabpane >}} + + {{< tabpane >}} {{< tab header="Config file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -92,15 +106,18 @@ params: } {{< /tab >}} {{< /tabpane >}} + ## Layout hooks -A number of layout partials and hooks are defined that can be used to customize the printed format. These can be found in `layouts/partials/print`. - -Hooks can be defined on a per-type basis. For example, you may want to customize the layouts of heading for "blog" pages vs "docs". This can be achieved by creating `layouts/partials/print/page-heading-.html` - eg. `page-heading-blog.html`. It defaults to using the page title and description as a heading. - -Similarly, the formatting for each page can be customized by creating `layouts/partials/print/content-.html`. - - +A number of layout partials and hooks are defined that can be used to customize +the printed format. These can be found in `layouts/_partials/print`. +Hooks can be defined on a per-type basis. For example, you may want to customize +the layouts of heading for "blog" pages vs "docs". This can be achieved by +creating `layouts/_partials/print/page-heading-.html` such as +`page-heading-blog.html`. It defaults to using the page title and description as +a heading. +Similarly, the formatting for each page can be customized by creating +`layouts/_partials/print/content-.html`. diff --git a/userguide/content/en/docs/adding-content/repository-links.md b/userguide/content/en/docs/adding-content/repository-links.md index 237d38b87b..96959c5ec9 100644 --- a/userguide/content/en/docs/adding-content/repository-links.md +++ b/userguide/content/en/docs/adding-content/repository-links.md @@ -2,29 +2,53 @@ title: Repository Links and other page information linkTitle: Repo links and page info weight: 9 -description: Help your users interact with page source and view page-source information. +description: + Help your users interact with page source and view page-source information. --- -The Docsy [docs and blog layouts](/docs/adding-content/content/#adding-docs-and-blog-posts) include links for readers to edit the page or create issues for your docs or project via your site's source repository. The current generated links for each docs or blog page are: - -* **View page source**: Brings the user to the page source in your docs repo. -* **Edit this page**: Brings the user to an editable version of the page content in their fork (if available) of your docs repo. If the user doesn't have a current fork of your docs repo, they are invited to create one before making their edit. The user can then create a pull request for your docs. -* **Create child page**: Brings the user to a create new file form in their fork of your docs repo. The new file will be located as a child of the page they clicked the link on. The form will be pre-populated with a template the user can edit to create their page. You can change this by adding `assets/stubs/new-page-template.md` to your own project. -* **Create documentation issue**: Brings the user to a new issue form in your docs repo with the name of the current page as the issue's title. -* **Create project issue** (optional): Brings the user to a new issue form in your project repo. This can be useful if you have separate project and docs repos and your users want to file issues against the project feature being discussed rather than your docs. +The Docsy +[docs and blog layouts](/docs/adding-content/content/#adding-docs-and-blog-posts) +include links for readers to edit the page or create issues for your docs or +project via your site's source repository. The current generated links for each +docs or blog page are: + +- **View page source**: Brings the user to the page source in your docs repo. +- **Edit this page**: Brings the user to an editable version of the page content + in their fork (if available) of your docs repo. If the user doesn't have a + current fork of your docs repo, they are invited to create one before making + their edit. The user can then create a pull request for your docs. +- **Create child page**: Brings the user to a create new file form in their fork + of your docs repo. The new file will be located as a child of the page they + clicked the link on. The form will be pre-populated with a template the user + can edit to create their page. You can change this by adding + `assets/stubs/new-page-template.md` to your own project. +- **Create documentation issue**: Brings the user to a new issue form in your + docs repo with the name of the current page as the issue's title. +- **Create project issue** (optional): Brings the user to a new issue form in + your project repo. This can be useful if you have separate project and docs + repos and your users want to file issues against the project feature being + discussed rather than your docs. This page shows you how to configure these links. -Currently, Docsy supports only GitHub repository links "out of the box". Since GitLab can handle the same link scheme, it should work as well. If you are using another repository such as Bitbucket and would like generated repository links, feel free to [add a feature request or update our theme](/docs/contribution-guidelines/). +Currently, Docsy supports only GitHub repository links "out of the box". Since +GitLab can handle the same link scheme, it should work as well. If you are using +another repository such as Bitbucket and would like generated repository links, +feel free to +[add a feature request or update our theme](/docs/contribution-guidelines/). ## Link configuration -There are four site variables you can configure in `hugo.toml`/`hugo.yaml`/`hugo.json` to set up links, as well as one in your page metadata. +There are four site variables you can configure in +`hugo.toml`/`hugo.yaml`/`hugo.json` to set up links, as well as one in your page +metadata. ### `github_repo` -The URL for your site's source repository. This is used to generate the **Edit this page**, **Create child page**, and **Create documentation issue** links. +The URL for your site's source repository. This is used to generate the **Edit +this page**, **Create child page**, and **Create documentation issue** links. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -43,11 +67,15 @@ params: } {{< /tab >}} {{< /tabpane >}} + ### `github_subdir` (optional) -Specify a value here if your content directory is not in your repo's root directory. For example, this site is in the `userguide` subdirectory of its repo. Setting this value means that your edit links will go to the right page. +Specify a value here if your content directory is not in your repo's root +directory. For example, this site is in the `userguide` subdirectory of its +repo. Setting this value means that your edit links will go to the right page. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -66,11 +94,15 @@ params: } {{< /tab >}} {{< /tabpane >}} + ### `github_project_repo` (optional) -Specify a value here if you have a separate project repo and you'd like your users to be able to create issues against your project from the relevant docs. The **Create project issue** link appears only if this is set. +Specify a value here if you have a separate project repo and you'd like your +users to be able to create issues against your project from the relevant docs. +The **Create project issue** link appears only if this is set. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -89,11 +121,14 @@ params: } {{< /tab >}} {{< /tabpane >}} + ### `github_branch` (optional) -Specify a value here if you have would like to reference a different branch for the other github settings like **Edit this page** or **Create project issue**. +Specify a value here if you have would like to reference a different branch for +the other github settings like **Edit this page** or **Create project issue**. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -112,6 +147,7 @@ params: } {{< /tab >}} {{< /tabpane >}} + ### `path_base_for_github_subdir` (optional) @@ -120,6 +156,7 @@ come from another repo, such as a [git submodule][]. Add settings like these to the **section's index page** so that the repository links for all pages in that section refer to the originating repo: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -153,6 +190,7 @@ cascade: } {{< /tab >}} {{< /tabpane >}} + As an example, consider a page at the path `content/some-section/subpath/some-page.md` with `github_branch` globally set to @@ -172,14 +210,14 @@ then also set `github_project_repo`, something like this: ```yaml --- -... +--- cascade: github_repo: &repo https://github.com/some-username/another-repo/ github_project_repo: *repo -... --- ``` + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -209,14 +247,17 @@ cascade: } {{< /tab >}} {{< /tabpane >}} + -{{% alert title="Tip" %}} -Please note that the YAML code fragment makes use of [Yaml anchor](https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/). Use of Yaml anchors is optional, but it helps keep the settings [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself). -{{% /alert %}} +{{% alert title="Tip" %}} Please note that the YAML code fragment makes use of +[Yaml anchor](https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/). +Use of Yaml anchors is optional, but it helps keep the settings +[DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself). {{% /alert %}} The `path_base_for_github_subdir` setting is a regular expression, so you can use it even if you have a site with [multiple languages][] for example: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -241,11 +282,13 @@ path_base_for_github_subdir: content/\w+/some-section } {{< /tab >}} {{< /tabpane >}} + In situations where a page originates from a file under a different name, you can specify `from` and `to` path-rename settings. Here's an example where an index file is named `README.md` in the originating repo: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -284,17 +327,21 @@ path_base_for_github_subdir: } {{< /tab >}} {{< /tabpane >}} + ### `github_url` (optional) -{{% alert title="Deprecation note" color="warning" %}} - This setting is deprecated. Use [path_base_for_github_subdir][] instead. +{{% alert title="Deprecation note" color="warning" %}} This setting is +deprecated. Use [path_base_for_github_subdir][] instead. + +[path_base_for_github_subdir]: #path_base_for_github_subdir-optional - [path_base_for_github_subdir]: #path_base_for_github_subdir-optional {{% /alert %}} -Specify a value for this **in your page metadata** to set a specific edit URL for this page, as in the following example: +Specify a value for this **in your page metadata** to set a specific edit URL +for this page, as in the following example: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -319,6 +366,7 @@ github_url: https://github.com/some-username/another-repo/edit/main/README.md } {{< /tab >}} {{< /tabpane >}} + This can be useful if you have page source files in multiple Git repositories, or require a non-GitHub URL. Pages using this value have **Edit this page** @@ -332,19 +380,21 @@ your [projects's `_styles_project.scss`][project-style-files] file to hide modifier -- not shown): ```scss -.td-page-meta__child { display: none; } +.td-page-meta__child { + display: none; +} ``` Each link kind has an associated unique class named `.td-page-meta__KIND`, as defined by the following table: -Link kind | Class name ---- | --- -View page source | `.td-page-meta__view` -Edit this page | `.td-page-meta__edit` -Create child page | `.td-page-meta__child` -Create documentation issue | `.td-page-meta__issue` -Create project issue | `.td-page-meta__project-issue` +| Link kind | Class name | +| -------------------------- | ------------------------------ | +| View page source | `.td-page-meta__view` | +| Edit this page | `.td-page-meta__edit` | +| Create child page | `.td-page-meta__child` | +| Create documentation issue | `.td-page-meta__issue` | +| Create project issue | `.td-page-meta__project-issue` | Of course, you can also use these classes to give repository links unique styles for your project. @@ -368,18 +418,22 @@ A last-modified page note looks something like this: >
style="margin-top: 0 !important; display: block !important;"> > -> Last modified November 29, 2023: [Release v0.8.0 preparation (#1756) (6bb4f99)](https://github.com/google/docsy/commit/6bb4f99d1eab4976fb80d1488c81ba12b1715c05) +> Last modified November 29, 2023: +> [Release v0.8.0 preparation (#1756) (6bb4f99)](https://github.com/google/docsy/commit/6bb4f99d1eab4976fb80d1488c81ba12b1715c05) +> >
-{.border-0} +> {.border-0} Once enabled site-wide, you can selectively hide last-modified notes in a page or section by declaring the following style (optionally with a `!important` modifier — not shown): ```scss -.td-page-meta__lastmod { display: none; } +.td-page-meta__lastmod { + display: none; +} ``` [git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[multiple languages]: {{% relref "language" %}} -[project-style-files]: {{% relref "lookandfeel#project-style-files" %}} +[multiple languages]: ../language/ +[project-style-files]: lookandfeel/#project-style-files diff --git a/userguide/content/en/docs/adding-content/search.md b/userguide/content/en/docs/adding-content/search.md index 09d1326099..7272d8b8d6 100644 --- a/userguide/content/en/docs/adding-content/search.md +++ b/userguide/content/en/docs/adding-content/search.md @@ -3,16 +3,29 @@ title: Search date: 2017-01-05 weight: 3.5 description: > - Let users search your Docsy site with a choice of configurable search options. + Let users search your Docsy site with a choice of configurable search options. +cSpell:ignore: GCSE --- -Docsy offers multiple options that let your readers search your site content, so you can pick one that suits your needs. You can choose from: - -* [Google Custom Search Engine](#configure-search-with-a-google-custom-search-engine) (GCSE), the default option, which uses Google's index of your public site to generate a search results page. -* [Algolia DocSearch](#algolia-docsearch), which uses Algolia's indexing and search mechanism. Search results are displayed as a pop-up. Algolia DocSearch is free for public documentation sites. -* [Local search with Lunr](#local-search-with-lunr), which uses Javascript to index and search your site without the need to connect to external services. This option doesn't require your site to be public. - -If you enable any of these search options in your project [configuration file], a search box displays in the right of your top navigation bar. By default a search box also displays at the top of the section menu in the left navigation pane, which you can disable if you prefer, or if you're using a search option that only works with the top search box. +Docsy offers multiple options that let your readers search your site content, so +you can pick one that suits your needs or [design your own](#custom-search). You +can choose from: + +- [Google Custom Search Engine](#configure-search-with-a-google-custom-search-engine) + (GCSE), the default option, which uses Google's index of your public site to + generate a search results page. +- [Algolia DocSearch](#algolia-docsearch), which uses Algolia's indexing and + search mechanism. Search results are displayed as a pop-up. Algolia DocSearch + is free for public documentation sites. +- [Local search with Lunr](#local-search-with-lunr), which uses Javascript to + index and search your site without the need to connect to external services. + This option doesn't require your site to be public. + +If you enable any of these search options in your project [configuration file], +a search box displays in the right of your top navigation bar. By default a +search box also displays at the top of the section menu in the left navigation +pane, which you can disable if you prefer, or if you're using a search option +that only works with the top search box. {{% alert title="You can only enable a single search option at a time" color=warning %}} @@ -24,8 +37,12 @@ behavior when serving your site. ## Disabling the sidebar search box -By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don't want the sidebar search box, set the site parameter `sidebar_search_disable` to `true` in `hugo.toml`/`hugo.yaml`/`hugo.json`: +By default, the search box appears in both the top navigation bar and at the top +of the sidebar left navigation pane. If you don't want the sidebar search box, +set the site parameter `sidebar_search_disable` to `true` in +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -45,31 +62,53 @@ params: } } } - {{< /tab >}} {{< /tabpane >}} + ## Configure search with a Google Custom Search Engine -By default Docsy uses a [Google Custom Search Engine](https://cse.google.com/cse/all) (GCSE) to search your site. To enable this feature, you'll first need to make sure that you have built and deployed [a production version of your site](/docs/deployment#build-environments-and-indexing), as otherwise your site won't be crawled and indexed. +By default Docsy uses a [Google Custom Search Engine][GCSE] (GCSE) to search +your site. To enable this feature, you'll first need to make sure that you have +built and deployed a +[production version of your site](/docs/deployment#build-environments-and-indexing), +as otherwise your site won't be crawled and indexed. ### Setting up site search -1. Create a Google Custom Search Engine for your deployed site by clicking **New search engine** on the [Custom Search page](https://cse.google.com/cse/all) and following the instructions. Make a note of the ID for your new search engine. -1. Add any further configuration you want to your search engine using the **Edit search engine** options. In particular you may want to do the following: - - * Select **Look and feel**. Change from the default **Overlay** layout to **Results only**, as this option means your search results are embedded in your search page rather than appearing in a separate box. Click **Save** to save your changes. - * Edit the default result link behavior so that search results from your site don't open in a new tab. To do this, select **Search Features** - **Advanced** - **Websearch Settings**. In the **Link Target** field, type "\_parent". Click **Save** to save your changes. +1. Create a Google Custom Search Engine for your deployed site by clicking + **New search engine** on the [Custom Search page][GCSE] and following the + instructions. Make a note of the ID for your new search engine. +1. Add any further configuration you want to your search engine using the + **Edit search engine** options. In particular you may want to do the + following: + + - Select **Look and feel**. Change from the default **Overlay** layout to + **Results only**, as this option means your search results are embedded in + your search page rather than appearing in a separate box. Click **Save** + to save your changes. + - Edit the default result link behavior so that search results from your + site don't open in a new tab. To do this, select **Search Features** - + **Advanced** - **Websearch Settings**. In the **Link Target** field, type + "\_parent". Click **Save** to save your changes. {{% alert title="Tip" %}} -Your site search results should show up within a couple of days. If it takes longer than that, you can manually request that your site is indexed by [submitting a sitemap through the Google Search Console](https://support.google.com/webmasters/answer/183668?hl=en). + +Your site search results should show up within a couple of days. If it takes +longer than that, you can manually request that your site is indexed by +[submitting a sitemap through the Google Search Console](https://support.google.com/webmasters/answer/183668?hl=en). + {{% /alert %}} ### Adding the search page Once you have your search engine set up, you can add the feature to your site: -1. Ensure you have a Markdown file in `content/en/search.md` (and one per other languages if needed) to display your search results. It only needs a title and `layout: search`, as in the following example: + + +1. Ensure you have a Markdown file in `content/en/search.md` (and one per other + languages if needed) to display your search results. It only needs a title + and `layout: search`, as in the following example: {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} @@ -93,7 +132,9 @@ layout: search {{< /tab >}} {{< /tabpane >}} -1. Add your Google Custom Search Engine ID to the site params in `hugo.toml`/`hugo.yaml`/`hugo.json`. You can add different values per language if needed. +1. Add your Google Custom Search Engine ID to the site params in + `hugo.toml`/`hugo.yaml`/`hugo.json`. You can add different values per + language if needed. {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} @@ -114,43 +155,50 @@ params: } {{< /tab >}} {{< /tabpane >}} - + ### Disabling GCSE search -If you don't specify a Google Custom Search Engine ID for your project and haven't enabled any other search options, the search box won't appear in your site. If you're using the default `hugo.toml` from the example site and want to disable search, just comment out or remove the relevant line. +If you don't specify a Google Custom Search Engine ID for your project and +haven't enabled any other search options, the search box won't appear in your +site. If you're using the default `hugo.toml` from the example site and want to +disable search, just comment out or remove the relevant line. ## Algolia DocSearch -As an alternative to GCSE, you can use [Algolia -DocSearch](https://docsearch.algolia.com), which is -free for public documentation sites. Docsy supports **Algolia DocSearch v3**. +As an alternative to GCSE, you can use +[Algolia DocSearch](https://docsearch.algolia.com), which is free for public +documentation sites. Docsy supports **Algolia DocSearch v3**. {{% alert title="Algolia v2 is deprecated" %}} + Docsy previously supported Algolia DocSearch v2, which is now deprecated. If you are an existing Algolia DocSearch v2 user and want to use the latest Docsy -version, [follow the migration -instructions](https://docsearch.algolia.com/docs/migrating-from-v2) in the -DocSearch documentation to update your DocSearch code snippet. +version, follow the +[migration instructions](https://docsearch.algolia.com/docs/migrating-from-v2) +in the DocSearch documentation to update your DocSearch code snippet. + {{% /alert %}} ### Sign up for Algolia DocSearch -Complete the form at . -Proceed to the next step once you've received Algolia DocSearch -parameters for your project. +Complete the form at . Proceed to the next +step once you've received Algolia DocSearch parameters for your project. ### Eager to test DocSearch? -Docsy defaults to the [Algolia test][]-site parameters when -none are provided. To enable search over the Algolia test, define -`params.search.algolia` without any other fields, as outlined next. +Docsy defaults to the [Algolia test][]-site parameters when none are provided. +To enable search over the Algolia test, define `params.search.algolia` without +any other fields, as outlined next. ### Configure Algolia DocSearch + + 1. Ensure that [GCSE search](#disabling-gcse-search) is disabled. 2. Add your project's Algolia DocSearch parameters to - `hugo.toml`/`hugo.yaml`/`hugo.json`, for example (using [Algolia test][] values): + `hugo.toml`/`hugo.yaml`/`hugo.json`, for example (using [Algolia test][] + values): {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} @@ -182,9 +230,10 @@ params: } {{< /tab >}} {{< /tabpane >}} + -To learn more about Algolia DocSearch V3, see [Getting -started](https://docsearch.algolia.com/docs/DocSearch-v3). +To learn more about Algolia DocSearch V3, see +[Getting started](https://docsearch.algolia.com/docs/DocSearch-v3). When you've completed these steps, Algolia search should be enabled on your site. Search results are displayed as a pop-up, so you don't need to add any @@ -195,20 +244,25 @@ search results page. You can customize or disable Docsy's default Algolia support by creating the following template files: -- `layouts/partials/algolia/head.html` used by `head.html` to load Algolia +- `layouts/_partials/algolia/head.html` used by `head.html` to load Algolia DocSearch styles. It also issues a deprecation warning for `params.algolia_docsearch`. -- `layouts/partials/algolia/scripts.html` used by `scripts.html` to load and +- `layouts/_partials/algolia/scripts.html` used by `scripts.html` to load and configure Algolia DocSearch. Leave either file empty to disable Docsy's implementation. ## Local search with Lunr -[Lunr](https://lunrjs.com/) is a Javascript-based search option that lets you index your site and make it searchable without the need for external, server-side search services. This is a good option particularly for smaller or non-public sites. +[Lunr](https://lunrjs.com/) is a Javascript-based search option that lets you +index your site and make it searchable without the need for external, +server-side search services. This is a good option particularly for smaller or +non-public sites. To add Lunr search to your Docsy site: + + 1. Enable local search in `hugo.toml`/`hugo.yaml`/`hugo.json`. {{< tabpane >}} @@ -230,18 +284,31 @@ params: {{< /tab >}} {{< /tabpane >}} -2. Remove or comment out any GCSE ID in `hugo.toml`/`hugo.yaml`/`hugo.json` and ensure Algolia DocSearch is set to `false`, as you can only have one type of search enabled. See [Disabling GCSE search](#disabling-gcse-search). +2. Remove or comment out any GCSE ID in `hugo.toml`/`hugo.yaml`/`hugo.json` and + ensure Algolia DocSearch is set to `false`, as you can only have one type of + search enabled. See [Disabling GCSE search](#disabling-gcse-search). -Once you've completed these steps, local search is enabled for your site and results appear in a drop down when you use the search box. + + +Once you've completed these steps, local search is enabled for your site and +results appear in a drop down when you use the search box. {{% alert title="Tip" %}} -If you're [testing this locally](/docs/deployment/#serving-your-site-locally) using Hugo’s local server functionality, you need to build your `offline-search-index.xxx.json` file first by running `hugo`. If you have the Hugo server running while you build `offline-search-index.xxx.json`, you may need to stop the server and restart it in order to see your search results. + +If you're [testing this locally](/docs/deployment/#serving-your-site-locally) +using Hugo’s local server functionality, you need to build your +`offline-search-index.xxx.json` file first by running `hugo`. If you have the +Hugo server running while you build `offline-search-index.xxx.json`, you may +need to stop the server and restart it in order to see your search results. + {{% /alert %}} ### Changing the summary length of the local search results -You can customize the summary length by setting `offlineSearchSummaryLength` in `hugo.toml`/`hugo.yaml`/`hugo.json`. +You can customize the summary length by setting `offlineSearchSummaryLength` in +`hugo.toml`/`hugo.yaml`/`hugo.json`. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -264,11 +331,14 @@ params: } {{< /tab >}} {{< /tabpane >}} + ### Changing the maximum result count of the local search -You can customize the maximum result count by setting `offlineSearchMaxResults` in `hugo.toml`/`hugo.yaml`/`hugo.json`. +You can customize the maximum result count by setting `offlineSearchMaxResults` +in `hugo.toml`/`hugo.yaml`/`hugo.json`. + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -290,12 +360,15 @@ params: } {{< /tab >}} {{< /tabpane >}} + ### Changing the width of the local search results popover -The width of the search results popover will automatically widen according to the content. +The width of the search results popover will automatically widen according to +the content. -If you want to limit the width, add the following scss into `assets/scss/_variables_project.scss`. +If you want to limit the width, add the following scss into +`assets/scss/_variables_project.scss`. ```scss .td-offline-search-results { @@ -305,8 +378,10 @@ If you want to limit the width, add the following scss into `assets/scss/_variab ### Excluding pages from local search results -To exclude pages from local search results, add `exclude_search: true` to the the frontmatter of each page: +To exclude pages from local search results, add `exclude_search: true` to the +the frontmatter of each page: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -318,7 +393,7 @@ exclude_search = true {{< /tab >}} {{< tab header="yaml" lang="yaml" >}} --- -title: "Index" +title: Index weight: 10 exclude_search: true --- @@ -331,6 +406,25 @@ exclude_search: true } {{< /tab >}} {{< /tabpane >}} + + +### Custom search + +If none of the supported search engines address your project's needs, you can +implement your own custom search. If your searchbox fits within Docsy's standard +design, then you can implement custom search by overriding the following files: + +- [layouts/_partials/search-input.html] +- [assets/scss/_search.scss] +- [assets/js/search.js] [algolia test]: https://docsearch.algolia.com/docs/legacy/dropdown/#testing -[configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file +[assets/js/search.js]: + https://github.com/google/docsy/blob/main/assets/js/search.js +[assets/scss/_search.scss]: + https://github.com/google/docsy/blob/main/assets/scss/_search.scss +[configuration file]: + https://gohugo.io/getting-started/configuration/#configuration-file +[GCSE]: https://cse.google.com/cse/all +[layouts/_partials/search-input.html]: + https://github.com/google/docsy/blob/main/layouts/_partials/search-input.html diff --git a/userguide/content/en/docs/adding-content/shortcodes/includes/config.yaml b/userguide/content/en/docs/adding-content/shortcodes/includes/config.yaml index e28cac21bf..aa1228aea0 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/includes/config.yaml +++ b/userguide/content/en/docs/adding-content/shortcodes/includes/config.yaml @@ -8,4 +8,4 @@ spec: image: alpine script: | #!/bin/sh - echo "Hello World" + echo "Hello World" diff --git a/userguide/content/en/docs/adding-content/shortcodes/includes/installation.md b/userguide/content/en/docs/adding-content/shortcodes/includes/installation.md index 8b93d3218c..f8cb6fbfb9 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/includes/installation.md +++ b/userguide/content/en/docs/adding-content/shortcodes/includes/installation.md @@ -1,14 +1,10 @@ **Installation** -{{% alert title="Note" color="primary" %}} -Check system compatibility before proceeding. -{{% /alert %}} +{{% alert title="Note" color="primary" %}} Check system compatibility before +proceeding. {{% /alert %}} 1. Download the installation files. -1. Run the installation script - - `sudo sh install.sh` +1. Run the installation script `sudo sh install.sh` 1. Test that your installation was successfully completed. - diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index 9bcdcc5aa5..2a91449bb2 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -6,12 +6,19 @@ weight: 5 description: > Use Docsy's Hugo shortcodes to quickly build site pages. resources: -- src: "**spruce*.jpg" - params: - byline: "*Photo*: Bjørn Erik Pedersen / CC-BY-SA" + - src: '**spruce*.jpg' + params: + byline: '*Photo*: Bjørn Erik Pedersen / CC-BY-SA' --- -Rather than writing all your site pages from scratch, Hugo lets you define and use [shortcodes](https://gohugo.io/content-management/shortcodes/). These are reusable snippets of content that you can include in your pages, often using HTML to create effects that are difficult or impossible to do in simple Markdown. Shortcodes can also have parameters that let you, for example, add your own text to a fancy shortcode text box. As well as Hugo's [built-in shortcodes](https://gohugo.io/content-management/shortcodes/), Docsy provides some shortcodes of its own to help you build your pages. +Rather than writing all your site pages from scratch, Hugo lets you define and +use [shortcodes](https://gohugo.io/content-management/shortcodes/). These are +reusable snippets of content that you can include in your pages, often using +HTML to create effects that are difficult or impossible to do in simple +Markdown. Shortcodes can also have parameters that let you, for example, add +your own text to a fancy shortcode text box. As well as Hugo's +[built-in shortcodes](https://gohugo.io/content-management/shortcodes/), Docsy +provides some shortcodes of its own to help you build your pages. ## Shortcode delimiters @@ -22,19 +29,25 @@ the shortcode body as Markdown. You can use both styles in your pages. ## Shortcode blocks -The theme comes with a set of custom **Page Block** shortcodes that can be used to compose landing pages, about pages, and similar. +The theme comes with a set of custom **Page Block** shortcodes that can be used +to compose landing pages, about pages, and similar. These blocks share some common parameters: -height -: A pre-defined height of the block container. One of `min`, `med`, `max`, `full`, or `auto`. Setting it to `full` will fill the Viewport Height, which can be useful for landing pages. - -color -: The block will be assigned a color from the theme palette if not provided, but you can set your own if needed. You can use all of Bootstrap's color names, theme color names or a grayscale shade. Some examples would be `primary`, `white`, `dark`, `warning`, `light`, `success`, `300`, `blue`, `orange`. This will become the **background color** of the block, but text colors will adapt to get proper contrast. +- **height**: A pre-defined height of the block container. One of `min`, `med`, + `max`, `full`, or `auto`. Setting it to `full` will fill the Viewport Height, + which can be useful for landing pages. +- **color**: The block will be assigned a color from the theme palette if not + provided, but you can set your own if needed. You can use all of Bootstrap's + color names, theme color names or a grayscale shade. Some examples would be + `primary`, `white`, `dark`, `warning`, `light`, `success`, `300`, `blue`, + `orange`. This will become the **background color** of the block, but text + colors will adapt to get proper contrast. ### blocks/cover -The **blocks/cover** shortcode creates a landing page type of block that fills the top of the page. +The **blocks/cover** shortcode creates a landing page type of block that fills +the top of the page. ```html {{}} @@ -53,28 +66,35 @@ The **blocks/cover** shortcode creates a landing page type of block that fills t {{}} ``` -Note that the relevant shortcode parameters above will have sensible defaults, but is included here for completeness. - -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| title | | The main display title for the block. | -| image_anchor | | -| height | | See above. -| color | | See above. -| byline | Byline text on featured image. | +Note that the relevant shortcode parameters above will have sensible defaults, +but is included here for completeness. +| Parameter | Default | Description | +| ------------ | ------------------------------ | ------------------------------------- | +| title | | The main display title for the block. | +| image_anchor | | +| height | | See above. | +| color | | See above. | +| byline | Byline text on featured image. | -To set the background image, place an image with the word "background" in the name in the page's [Page Bundle](/docs/adding-content/content/#page-bundles). For example, in our the example site the background image in the home page's cover block is [`featured-background.jpg`](https://github.com/google/docsy-example/tree/main/content/en), in the same directory. +To set the background image, place an image with the word "background" in the +name in the page's [Page Bundle](/docs/adding-content/content/#page-bundles). +For example, in our the example site the background image in the home page's +cover block is +[`featured-background.jpg`](https://github.com/google/docsy-example/tree/main/content/en), +in the same directory. -{{% alert title="Tip" %}} -If you also include the word **featured** in the image name, e.g. `my-featured-background.jpg`, it will also be used as the Twitter Card image when shared. -{{% /alert %}} +{{% alert title="Tip" %}} If you also include the word **featured** in the image +name, e.g. `my-featured-background.jpg`, it will also be used as the Twitter +Card image when shared. {{% /alert %}} -For available icons, see [Font Awesome](https://fontawesome.com/icons?d=gallery&m=free). +For available icons, see +[Font Awesome](https://fontawesome.com/icons?d=gallery&m=free). ### blocks/lead -The **blocks/lead** block shortcode is a simple lead/title block with centred text and an arrow down pointing to the next section. +The **blocks/lead** block shortcode is a simple lead/title block with centred +text and an arrow down pointing to the next section. ```go-html-template {{%/* blocks/lead color="dark" */%}} @@ -85,17 +105,18 @@ Runs on **bare metal** in the **cloud**! ``` | Parameter | Default | Description | -| --------- |--------- | ----------------------------------------- | +| --------- | -------- | ----------------------------------------- | | height | `auto` | See [Shortcode blocks](#shortcode-blocks) | | color | .Ordinal | See [Shortcode blocks](#shortcode-blocks) | ### blocks/section -The **blocks/section** shortcode is meant as a general-purpose content container. It comes in two "flavors", one for general content and one with styling more suitable for wrapping a horizontal row of feature sections. +The **blocks/section** shortcode is meant as a general-purpose content +container. It comes in two "flavors", one for general content and one with +styling more suitable for wrapping a horizontal row of feature sections. The example below shows a section wrapping 3 feature sections. - ```go-html-template {{}} {{%/* blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" */%}} @@ -111,11 +132,11 @@ For announcement of latest features etc. {{}} ``` -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| `height` | | See above. -| `color` | | See above. -| `type` | | Specify "container" (the default) if you want a general container, or "row" if the section will contain columns -- which must be immediate children. +| Parameter | Default | Description | +| --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `height` | | See above. | +| `color` | | See above. | +| `type` | | Specify "container" (the default) if you want a general container, or "row" if the section will contain columns -- which must be immediate children. | ### blocks/feature @@ -125,17 +146,17 @@ We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions wor {{%/* /blocks/feature */%}} ``` -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| title | | The title to use. -| url | | The URL to link to. -| url_text | The [language parameter](/docs/language/#internationalization-bundles) value of [`ui_read_more`](https://github.com/google/docsy/blob/main/i18n/en.toml) | The link text to use. -| icon | | The icon class to use. - +| Parameter | Default | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| title | | The title to use. | +| url | | The URL to link to. | +| url_text | The [language parameter](/docs/language/#internationalization-bundles) value of [`ui_read_more`](https://github.com/google/docsy/blob/main/i18n/en.toml) | The link text to use. | +| icon | | The icon class to use. | ### blocks/link-down -The **blocks/link-down** shortcode creates a navigation link down to the next section. It's meant to be used in combination with the other blocks shortcodes. +The **blocks/link-down** shortcode creates a navigation link down to the next +section. It's meant to be used in combination with the other blocks shortcodes. ```go-html-template
@@ -143,15 +164,16 @@ The **blocks/link-down** shortcode creates a navigation link down to the next se
``` -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| color | info | See above. +| Parameter | Default | Description | +| --------- | ------- | ----------- | +| color | info | See above. | ## Shortcode helpers ### alert -The **alert** shortcode creates an alert block that can be used to display notices or warnings. +The **alert** shortcode creates an alert block that can be used to display +notices or warnings. ```go-html-template {{%/* alert title="Warning" color="warning" */%}} @@ -161,17 +183,18 @@ This is a warning. Renders to: -{{% alert title="Warning" color="warning" %}} -This is a warning. -{{% /alert %}} +{{% alert title="Warning" color="warning" %}} This is a warning. {{% /alert %}} -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| color | primary | One of the theme colors, eg `primary`, `info`, `warning` etc. +| Parameter | Default | Description | +| --------- | ------- | ------------------------------------------------------------- | +| color | primary | One of the theme colors, eg `primary`, `info`, `warning` etc. | ### pageinfo -The **pageinfo** shortcode creates a text box that you can use to add banner information for a page: for example, letting users know that the page contains placeholder content, that the content is deprecated, or that it documents a beta feature. +The **pageinfo** shortcode creates a text box that you can use to add banner +information for a page: for example, letting users know that the page contains +placeholder content, that the content is deprecated, or that it documents a beta +feature. ```go-html-template {{%/* pageinfo color="info" */%}} @@ -182,17 +205,20 @@ This is placeholder content. Renders to: {{% pageinfo color="info" %}} + This is placeholder content -{{% /pageinfo %}} -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| color | primary | One of the theme colors, eg `primary`, `info`, `warning` etc. +{{% /pageinfo %}} +| Parameter | Default | Description | +| --------- | ------- | ------------------------------------------------------------- | +| color | primary | One of the theme colors, eg `primary`, `info`, `warning` etc. | ### imgproc -The **imgproc** shortcode finds an image in the current [Page Bundle](/docs/adding-content/content/#page-bundles) and scales it given a set of processing instructions. +The **imgproc** shortcode finds an image in the current +[Page Bundle](/docs/adding-content/content/#page-bundles) and scales it given a +set of processing instructions. ```go-html-template {{%/* imgproc spruce Fill "400x450" */%}} @@ -200,14 +226,21 @@ Norway Spruce *Picea abies* shoot with foliage buds. {{%/* /imgproc */%}} ``` -Use the syntax above if the inner content and/or the `byline` parameter of your shortcode is authored in markdown. In case of HTML content, use `<>` as innermost delimiters: `{{}}HTML content{{< /imgproc */>}}`. +Use the syntax above if the inner content and/or the `byline` parameter of your +shortcode is authored in markdown. In case of HTML content, use `<>` as +innermost delimiters: `{{}}HTML content{{< /imgproc */>}}`. -{{% imgproc spruce Fill "400x450" %}} -Norway Spruce *Picea abies* shoot with foliage buds. -{{% /imgproc %}} +{{% imgproc spruce Fill "400x450" %}} Norway Spruce _Picea abies_ shoot with +foliage buds. {{% /imgproc %}} -The example above has also a byline with photo attribution added. When using illustrations with a free license from [WikiMedia](https://commons.wikimedia.org/) and similar, you will in most situations need a way to attribute the author or licensor. You can add metadata to your page resources in the page front matter. The `byline` param is used by convention in this theme: +The example above has also a byline with photo attribution added. When using +illustrations with a free license from +[WikiMedia](https://commons.wikimedia.org/) and similar, you will in most +situations need a way to attribute the author or licensor. You can add metadata +to your page resources in the page front matter. The `byline` param is used by +convention in this theme: + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -240,17 +273,24 @@ resources: } {{< /tab >}} {{< /tabpane >}} + -| Parameter | Description | -| ----------------: |------------| -| 1 | The image filename or enough of it to identify it (we do Glob matching) -| 2 | Command. One of `Fit`, `Resize`, `Fill` or `Crop`. See [Image Processing Methods](https://gohugo.io/content-management/image-processing/#image-processing-methods). -| 3 | Processing options, e.g. `400x450 r180`. See [Image Processing Options](https://gohugo.io/content-management/image-processing/#image-processing-options). +| Parameter | Description | +| --------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | The image filename or enough of it to identify it (we do Glob matching) | +| 2 | Command. One of `Fit`, `Resize`, `Fill` or `Crop`. See [Image Processing Methods](https://gohugo.io/content-management/image-processing/#image-processing-methods). | +| 3 | Processing options, e.g. `400x450 r180`. See [Image Processing Options](https://gohugo.io/content-management/image-processing/#image-processing-options). | ### swaggerui -You can place the `swaggerui` shortcode anywhere inside a page with the [`swagger` layout](https://github.com/google/docsy/tree/main/layouts/swagger); it renders [Swagger UI](https://swagger.io/tools/swagger-ui/) using any OpenAPI YAML or JSON file as source. This file can be hosted anywhere you like, for example in your site's root [`/static` folder](/docs/adding-content/content/#adding-static-content). +You can place the `swaggerui` shortcode anywhere inside a page with the +[`swagger` layout](https://github.com/google/docsy/tree/main/layouts/swagger); +it renders [Swagger UI](https://swagger.io/tools/swagger-ui/) using any OpenAPI +YAML or JSON file as source. This file can be hosted anywhere you like, for +example in your site's root +[`/static` folder](/docs/adding-content/content/#adding-static-content). + {{< tabpane >}} {{< tab header="Front matter:" disabled=true />}} {{< tab header="toml" lang="toml" >}} @@ -284,51 +324,80 @@ description: Reference for the Pet Store API {{}} {{< /tab >}} {{< /tabpane >}} + -You can customize Swagger UI's look and feel by overriding Swagger's CSS in `themes/docsy/assets/scss/_swagger.scss`. +You can customize Swagger UI's look and feel by overriding Swagger's CSS in +`themes/docsy/assets/scss/_swagger.scss`. + +{{% alert title="Warning" color="warning" %}} This shortcode relies on +JavaScript libraries hosted on unpkg. Make sure that you can access unpkg from +your network when building or loading your site. {{% /alert %}} ### redoc -The `redoc` shortcode uses the open-source [Redoc](https://github.com/Redocly/redoc) tool to render reference API documentation from an OpenAPI YAML or JSON file. This can be hosted anywhere you like, for example in your site's root [`/static` folder](/docs/adding-content/content/#adding-static-content), but you can use a URL as well, for example: +The `redoc` shortcode uses the open-source +[Redoc](https://github.com/Redocly/redoc) tool to render reference API +documentation from an OpenAPI YAML or JSON file. This can be hosted anywhere you +like, for example in your site's root +[`/static` folder](/docs/adding-content/content/#adding-static-content), but you +can use a URL as well, for example: ```yaml --- -title: "Pet Store API" +title: 'Pet Store API' type: docs weight: 1 description: Reference for the Pet Store API --- - -{{}} +{ + { + , + }, +} ``` ### iframe -With this shortcode you can embed external content into a Docsy page as an inline frame (`iframe`) - see: https://www.w3schools.com/tags/tag_iframe.asp - -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| src | | URL of external content -| width | 100% | Width of iframe -| tryautoheight | true | If true the shortcode tries to calculate the needed height for the embedded content using JavaScript, as described here: https://stackoverflow.com/a/14618068. This is only possible if the embedded content is [on the same domain](https://stackoverflow.com/questions/22086722/resize-cross-domain-iframe-height). Note that even if the embedded content is on the same domain, it depends on the structure of the content if the height can be calculated correctly. -| style | min-height:98vh; border:none; | CSS styles for the iframe. `min-height:98vh;` is a backup if `tryautoheight` doesn't work. `border:none;` removes the border from the iframe - this is useful if you want the embedded content to look more like internal content from your page. -| sandbox | false | You can switch the sandbox completely on by setting `sandbox = true` or allow specific functionality with the common values for the iframe parameter `sandbox` defined in the [HTML standard](https://www.w3schools.com/tags/att_iframe_sandbox.asp). -| name | iframe-name | Specify the [name of the iframe](https://www.w3schools.com/tags/att_iframe_name.asp). -| id | iframe-id | Sets the ID of the iframe. -| class | | Optional parameter to set the classes of the iframe. -| sub | Your browser cannot display embedded frames. You can access the embedded page via the following link: | The text displayed (in addition to the embedded URL) if the user's browser can't display embedded frames. - -{{% alert title="Warning" color="warning" %}} -You can only embed external content from a server when its `X-Frame-Options` is not set or if it specifically allows embedding for your site. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options for details. - -There are several tools you can use to check if a website can be embedded via iframe - e.g.: https://gf.dev/x-frame-options-test. Be aware that when this test says "Couldn’t find the X-Frame-Options header -in the response headers." you __CAN__ embed it, but when the test says "Great! X-Frame-Options header was found in the HTTP response headers as highlighted below.", you __CANNOT__ - unless it has been explicitly enabled for your site. -{{% /alert %}} +With this shortcode you can embed external content into a Docsy page as an +inline frame (`iframe`) - see: https://www.w3schools.com/tags/tag_iframe.asp + +| Parameter | Default | Description | +| ------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| src | | URL of external content | +| width | 100% | Width of iframe | +| tryautoheight | true | If true the shortcode tries to calculate the needed height for the embedded content using JavaScript, see [details](https://stackoverflow.com/questions/9162933?no-link-check). This is only possible if the embedded content is [on the same domain](https://stackoverflow.com/questions/22086722/resize-cross-domain-iframe-height?no-link-check). Note that even if the embedded content is on the same domain, it depends on the structure of the content if the height can be calculated correctly. | +| style | min-height:98vh; border:none; | CSS styles for the iframe. `min-height:98vh;` is a backup if `tryautoheight` doesn't work. `border:none;` removes the border from the iframe - this is useful if you want the embedded content to look more like internal content from your page. | +| sandbox | false | You can switch the sandbox completely on by setting `sandbox = true` or allow specific functionality with the common values for the iframe parameter `sandbox` defined in the [HTML standard](https://www.w3schools.com/tags/att_iframe_sandbox.asp). | +| name | iframe-name | Specify the [name of the iframe](https://www.w3schools.com/tags/att_iframe_name.asp). | +| id | iframe-id | Sets the ID of the iframe. | +| class | | Optional parameter to set the classes of the iframe. | +| sub | Your browser cannot display embedded frames. You can access the embedded page via the following link: | The text displayed (in addition to the embedded URL) if the user's browser can't display embedded frames. | + +{{% alert title="Warning" color="warning" %}} You can only embed external +content from a server when its `X-Frame-Options` is not set or if it +specifically allows embedding for your site. See +https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options for +details. + +There are several tools you can use to check if a website can be embedded via +iframe - e.g.: https://gf.dev/x-frame-options-test. Be aware that when this test +says "Couldn’t find the X-Frame-Options header in the response headers." you +**CAN** embed it, but when the test says "Great! X-Frame-Options header was +found in the HTTP response headers as highlighted below.", you **CANNOT** - +unless it has been explicitly enabled for your site. {{% /alert %}} ## Tabbed panes -Sometimes it's very useful to have tabbed panes when authoring content. One common use-case is to show multiple syntax highlighted code blocks that showcase the same problem, and how to solve it in different programming languages. As an example, the tabbed pane below shows the language-specific variants of the famous `Hello world!` program one usually writes first when learning a new programming language: +Sometimes it's very useful to have tabbed panes when authoring content. One +common use-case is to show multiple syntax highlighted code blocks that showcase +the same problem, and how to solve it in different programming languages. As an +example, the tabbed pane below shows the language-specific variants of the +famous `Hello world!` program one usually writes first when learning a new +programming language: + {{< tabpane langEqualsHeader=true >}} {{< tab "C" >}} #include @@ -387,8 +456,12 @@ object HelloWorld extends App { } {{< /tab >}} {{< /tabpane >}} + -The Docsy template provides two shortcodes `tabpane` and `tab` that let you easily create tabbed panes. To see how to use them, have a look at the following code block, which renders to a right aligned pane with one disabled and three active tabs: +The Docsy template provides two shortcodes `tabpane` and `tab` that let you +easily create tabbed panes. To see how to use them, have a look at the following +code block, which renders to a right aligned pane with one disabled and three +active tabs: ```go-html-template {{}} @@ -408,8 +481,10 @@ The Docsy template provides two shortcodes `tabpane` and `tab` that let you easi {{}} ``` -This code translates to the right aligned tabbed pane below, showing a `Welcome!` greeting in English, German or Swahili: +This code translates to the right aligned tabbed pane below, showing a +`Welcome!` greeting in English, German or Swahili: + {{< tabpane text=true right=true >}} {{% tab header="**Languages**:" disabled=true /%}} {{% tab header="English" lang="en" %}} @@ -425,6 +500,7 @@ This code translates to the right aligned tabbed pane below, showing a `Welcome! **Karibu sana!** {{% /tab %}} {{< /tabpane >}} + ### Shortcode details @@ -439,12 +515,13 @@ the following named parameters, all of which are optional: - **`lang`**: the default code-block language to use for all contained tabs - **`highlight`**: parameter passed on to the code-block [highlight] function, as described below -- **`langEqualsHeader`**: set to `true` when header text matches the tab language. +- **`langEqualsHeader`**: set to `true` when header text matches the tab + language. - **`persist`**: one of `header`, `lang`, or `disabled` - **`persistLang`**: deprecated, use `persist` instead - **`right`**: set to `true` if you want right-aligned tabs -- **`text`**: set to `true` if the content of all contained tabs are text. Default - is `false` and assumes the content is code. +- **`text`**: set to `true` if the content of all contained tabs are text. + Default is `false` and assumes the content is code. The value of the optional parameters `lang` and `highlight` are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [highlight] @@ -461,16 +538,16 @@ Tab selection is persisted by default. When unspecified, `persist` defaults to The `tab` shortcode represent the tabs you want to show. It supports the following named parameters, all of which are optional: -- **`header`**: defines the tab's header text. When omitted it defaults to text of - the form "Tab _n_". You can omit the parameter name if it is the only tab +- **`header`**: defines the tab's header text. When omitted it defaults to text + of the form "Tab _n_". You can omit the parameter name if it is the only tab parameter: ``` {{}} … {{}} ``` - **`lang`**: code-block language for code tabs - **`highlight`**: parameter passed on to the code-block [highlight] function -- **`right`**: set to `true` in order to split tab panes into a left aligned and a - right aligned tab groups. Specify `right=true` in the dividing tab. By using +- **`right`**: set to `true` in order to split tab panes into a left aligned and + a right aligned tab groups. Specify `right=true` in the dividing tab. By using `right=true` more than once, you can even render multiple tab groups. - **`disabled`**: set to `true` to disable a tab. - **`text`**: set to `true` for text tabs. By default tabs are assumed to @@ -495,31 +572,40 @@ and _textual_ representation: ## Card panes -When authoring content, it's sometimes very useful to put similar text blocks or code fragments on card like elements, which can be optionally presented side by side. Let's showcase this feature with the following sample card group which shows the first four Presidents of the United States: +When authoring content, it's sometimes very useful to put similar text blocks or +code fragments on card like elements, which can be optionally presented side by +side. Let's showcase this feature with the following sample card group which +shows the first four Presidents of the United States: {{% cardpane %}} {{% card header="**George Washington**" title="\*1732     †1799" subtitle="**President:** 1789 – 1797" footer="![SignatureGeorgeWashington](https://upload.wikimedia.org/wikipedia/commons/thumb/2/2e/George_Washington_signature.svg/320px-George_Washington_signature.svg.png 'Signature George Washington')" %}} -![PortraitGeorgeWashington](https://upload.wikimedia.org/wikipedia/commons/thumb/b/b6/Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg/633px-Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg "Portrait George Washington") +![PortraitGeorgeWashington](https://upload.wikimedia.org/wikipedia/commons/thumb/b/b6/Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg/633px-Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg 'Portrait George Washington') {{% /card %}} {{% card header="**John Adams**" title="\* 1735     † 1826" subtitle="**President:** 1797 – 1801" footer="![SignatureJohnAdams](https://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/John_Adams_Sig_2.svg/320px-John_Adams_Sig_2.svg.png 'Signature John Adams')" %}} -![PortraitJohnAdams](https://upload.wikimedia.org/wikipedia/commons/thumb/f/ff/Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg/633px-Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg "Portrait John Adams") +![PortraitJohnAdams](https://upload.wikimedia.org/wikipedia/commons/thumb/f/ff/Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg/633px-Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg 'Portrait John Adams') {{% /card %}} {{% card header="**Thomas Jefferson**" title="\* 1743     † 1826" subtitle="**President:** 1801 – 1809" footer="![SignatureThomasJefferson](https://upload.wikimedia.org/wikipedia/commons/thumb/0/0d/Thomas_Jefferson_Signature.svg/320px-Thomas_Jefferson_Signature.svg.png 'Signature Thomas Jefferson')" %}} -![PortraitThomasJefferson](https://upload.wikimedia.org/wikipedia/commons/thumb/b/b1/Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg/390px-Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg "Portrait Thomas Jefferson") +![PortraitThomasJefferson](https://upload.wikimedia.org/wikipedia/commons/thumb/b/b1/Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg/390px-Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg 'Portrait Thomas Jefferson') {{% /card %}} {{% card header="**James Madison**" title="\* 1751     † 1836" subtitle="**President:** 1809 – 1817" footer="![SignatureJamesMadison](https://upload.wikimedia.org/wikipedia/commons/thumb/3/39/James_Madison_sig.svg/320px-James_Madison_sig.svg.png 'Signature James Madison')" %}} -![PortraitJamesMadison](https://upload.wikimedia.org/wikipedia/commons/thumb/2/20/James_Madison%28cropped%29%28c%29.jpg/393px-James_Madison%28cropped%29%28c%29.jpg "Portrait James Madison") -{{% /card %}} -{{% /cardpane %}} +![PortraitJamesMadison](https://upload.wikimedia.org/wikipedia/commons/thumb/2/20/James_Madison%28cropped%29%28c%29.jpg/393px-James_Madison%28cropped%29%28c%29.jpg 'Portrait James Madison') +{{% /card %}} {{% /cardpane %}} Docsy supports creating such card panes via different shortcodes: -* The `cardpane` shortcode which is the container element for the various cards to be presented. -* The `card` shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A `card` shortcode can hold programming code, text, images or any other arbitrary kind of markdown or HTML markup as content. In case of programming code, cards provide automatic code-highlighting and other optional features like line numbers, highlighting of certain lines, …. +- The `cardpane` shortcode which is the container element for the various cards + to be presented. +- The `card` shortcodes, with each shortcode representing an individual card. + While cards are often presented inside a card group, a single card may stand + on its own, too. A `card` shortcode can hold programming code, text, images or + any other arbitrary kind of markdown or HTML markup as content. In case of + programming code, cards provide automatic code-highlighting and other optional + features like line numbers, highlighting of certain lines, …. ### Shortcode `card`: textual content -Make use of the `card` shortcode to display a card. The following code sample demonstrates how to code a card element: +Make use of the `card` shortcode to display a card. The following code sample +demonstrates how to code a card element: ```go-html-template {{}} ``` -This code translates to the left card shown below, showing the lyrics of John Lennon's famous song `Imagine`. A second explanatory card element to the right indicates and explains the individual components of a card: + +This code translates to the left card shown below, showing the lyrics of John +Lennon's famous song `Imagine`. A second explanatory card element to the right +indicates and explains the individual components of a card: {{% cardpane %}} {{< card header="**Imagine**" title="Artist and songwriter: John Lennon" subtitle="Co-writer: Yoko Ono" footer="![SignatureJohnLennon](https://upload.wikimedia.org/wikipedia/commons/thumb/5/51/Firma_de_John_Lennon.svg/320px-Firma_de_John_Lennon.svg.png 'Signature John Lennon')" >}} -Imagine there's no heaven, It's easy if you try
-No hell below us, above us only sky
-Imagine all the people living for today… +Imagine there's no heaven, It's easy if you try
No hell below us, above us +only sky
Imagine all the people living for today… -Imagine there's no countries, it isn't hard to do
-Nothing to kill or die for, and no religion too
-Imagine all the people living life in peace… +Imagine there's no countries, it isn't hard to do
Nothing to kill or die +for, and no religion too
Imagine all the people living life in peace… -Imagine no possessions, I wonder if you can
-No need for greed or hunger - a brotherhood of man
-Imagine all the people sharing all the world… +Imagine no possessions, I wonder if you can
No need for greed or hunger - a +brotherhood of man
Imagine all the people sharing all the world… -You may say I'm a dreamer, but I'm not the only one
-I hope someday you'll join us and the world will live as one -{{< /card >}} +You may say I'm a dreamer, but I'm not the only one
I hope someday you'll +join us and the world will live as one {{< /card >}} {{% card header="**Header**: specified via named parameter `Header`" title="**Card title**: specified via named parameter `title`" subtitle="**Card subtitle**: specified via named parameter `subtitle`" footer="**Footer**: specified via named parameter `footer`" %}} - **Content**: inner content of the shortcode, this may be plain text or formatted text, images, videos, … . If your content is markdown, use the percent sign `%` as outermost delimiter of your `card` shortcode, your markup should look like `{{%/* card */%}}Your **markdown** content{{%/* /card */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{}}Your HTML content{{}}` -{{% /card %}} +**Content**: inner content of the shortcode, this may be plain text or formatted +text, images, videos, … . If your content is markdown, use the percent sign `%` +as outermost delimiter of your `card` shortcode, your markup should look like +`{{%/* card */%}}Your **markdown** content{{%/* /card */%}}`. In case of HTML +content, use square brackets `<>` as outermost delimiters: +`{{}}Your HTML content{{}}` {{% /card %}} {{% /cardpane %}} -While the main content of the card is taken from the inner markup of the `card` shortcode, the optional elements `footer`, `header`, `title`, and `subtitle` are all specified as named parameters of the shortcode. +While the main content of the card is taken from the inner markup of the `card` +shortcode, the optional elements `footer`, `header`, `title`, and `subtitle` are +all specified as named parameters of the shortcode. ### Shortcode `card`: programming code -If you want to display programming code on your card, set the named parameter `code` of the card to `true`. The following sample demonstrates how to code a card element with the famous `Hello world!` application coded in C: +If you want to display programming code on your card, set the named parameter +`code` of the card to `true`. The following sample demonstrates how to code a +card element with the famous `Hello world!` application coded in C: ```go-html-template {{}} @@ -576,23 +669,22 @@ int main(void) This code translates to the card shown below: -{{< card code=true header="**C**" lang="C" highlight="" >}} -#include +{{< card code=true header="**C**" lang="C" highlight="" >}} #include #include -int main(void) -{ - puts("Hello World!"); - return EXIT_SUCCESS; -} -{{< /card >}} +int main(void) { puts("Hello World!"); return EXIT_SUCCESS; } {{< /card >}} -
If called with parameter `code=true`, the `card` shortcode can optionally hold the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code block presented on the card. +
If called with parameter `code=true`, the `card` shortcode can optionally +hold the named parameters `lang` and/or `highlight`. The values of these +optional parameters are passed on as second `LANG` and third `OPTIONS` arguments +to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) +function which is used to render the code block presented on the card. ### Card groups -Displaying two ore more cards side by side can be easily achieved by putting them between the opening and closing elements of a `cardpane` shortcode. -The general markup of a card group resembles closely the markup of a tabbed pane: +Displaying two ore more cards side by side can be easily achieved by putting +them between the opening and closing elements of a `cardpane` shortcode. The +general markup of a card group resembles closely the markup of a tabbed pane: ```go-html-template {{}} @@ -608,21 +700,15 @@ The general markup of a card group resembles closely the markup of a tabbed pane {{}} ``` -Contrary to tabs, cards are presented side by side, however. This is especially useful it you want to compare different programming techniques (traditional vs. modern) on two cards, like demonstrated in the example above: +Contrary to tabs, cards are presented side by side, however. This is especially +useful it you want to compare different programming techniques (traditional vs. +modern) on two cards, like demonstrated in the example above: -{{< cardpane >}} -{{< card code=true header="**Java 5**" >}} -File[] hiddenFiles = new File("directory_name") - .listFiles(new FileFilter() { - public boolean accept(File file) { - return file.isHidden(); - } - }); -{{< /card >}} -{{< card code=true header="**Java 8, Lambda expression**" >}} -File[] hiddenFiles = new File("directory_name") - .listFiles(File::isHidden); -{{< /card >}} +{{< cardpane >}} {{< card code=true header="**Java 5**" >}} File[] hiddenFiles = +new File("directory_name") .listFiles(new FileFilter() { public boolean +accept(File file) { return file.isHidden(); } }); {{< /card >}} +{{< card code=true header="**Java 8, Lambda expression**" >}} File[] hiddenFiles += new File("directory_name") .listFiles(File::isHidden); {{< /card >}} {{< /cardpane >}} ## Include external files @@ -676,8 +762,8 @@ The following section explains how to install the database: --- -The parameter is the relative path to the file. Only relative paths -under the parent file's working directory are supported. +The parameter is the relative path to the file. Only relative paths under the +parent file's working directory are supported. For files outside the current working directory you can use an absolute path starting with `/`. The root directory is the `/content` folder. @@ -698,8 +784,8 @@ To create a new pipeline, follow the next steps: 1. Apply the file to your cluster `kubectl apply config.yaml` ``` -This code automatically reads the content of `includes/config.yaml` and inserts it -into the document. The rendered text looks like this: +This code automatically reads the content of `includes/config.yaml` and inserts +it into the document. The rendered text looks like this: --- @@ -713,34 +799,35 @@ To create a new pipeline, follow the next steps: --- -{{% alert title="Warning" color="warning" %}} -You must use `{{}}` delimiters for the code highlighting to work -correctly. -{{% /alert %}} +{{% alert title="Warning" color="warning" %}} You must use `{{}}` +delimiters for the code highlighting to work correctly. {{% /alert %}} -The `file` parameter is the relative path to the file. Only relative paths -under the parent file's working directory are supported. +The `file` parameter is the relative path to the file. Only relative paths under +the parent file's working directory are supported. For files outside the current working directory you can use an absolute path starting with `/`. The root directory is the `/content` folder. -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| file | | Path of external file| -| code | false | Boolean value. If `true` the contents is treated as code| -| lang | plain text | Programming language | +| Parameter | Default | Description | +| --------- | ---------- | -------------------------------------------------------- | +| file | | Path of external file | +| code | false | Boolean value. If `true` the contents is treated as code | +| lang | plain text | Programming language | ### Error reporting -If the shortcode can't find the specified file, the shortcode throws a compile error. +If the shortcode can't find the specified file, the shortcode throws a compile +error. -In the following example, Hugo throws a compile error if it can't find `includes/deploy.yml`: +In the following example, Hugo throws a compile error if it can't find +`includes/deploy.yml`: ```go-html-template {{}} ``` -Alternately, Hugo you can display a message on the rendered page instead of throwing a compile error. Add `draft="true"` as a parameter. For example: +Alternately, Hugo you can display a message on the rendered page instead of +throwing a compile error. Add `draft="true"` as a parameter. For example: ```go-html-template {{}} @@ -748,7 +835,11 @@ Alternately, Hugo you can display a message on the rendered page instead of thro ## Conditional text -The `conditional-text` shortcode allows you to show or hide parts of your content depending on the value of the `buildCondition` parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds. +The `conditional-text` shortcode allows you to show or hide parts of your +content depending on the value of the `buildCondition` parameter set in your +configuration file. This can be useful if you are generating different builds +from the same source, for example, using a different product name. This +shortcode helps you handle the minor differences between these builds. ```text {{%/* conditional-text include-if="foo" */%}} @@ -759,6 +850,9 @@ This text does not appear in the output if `buildCondition = "bar" is set in you {{%/* /conditional-text */%}} ``` -If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set `include-if="foobar"`, and `buildcondition = "foo"`, you have a match! +If you are using this shortcode, note that when evaluating the conditions, +substring matches are matches as well. That means, if you set +`include-if="foobar"`, and `buildcondition = "foo"`, you have a match! -[shortcode delimiter]: https://gohugo.io/content-management/shortcodes/#use-shortcodes +[shortcode delimiter]: + https://gohugo.io/content-management/shortcodes/#use-shortcodes diff --git a/userguide/content/en/docs/adding-content/taxonomy.md b/userguide/content/en/docs/adding-content/taxonomy.md index dd9e086419..2554305536 100644 --- a/userguide/content/en/docs/adding-content/taxonomy.md +++ b/userguide/content/en/docs/adding-content/taxonomy.md @@ -1,60 +1,70 @@ --- -title: "Taxonomy Support" -linkTitle: "Taxonomy Support" +title: Taxonomy Support weight: 10 -tags: ["Tagging", "Structuring Content", "Labelling"] -categories: ["Taxonomies"] +tags: [Tagging, Structuring Content, Labelling] +categories: [Taxonomies] description: > Structure the content using taxonomies like tags, categories, labels. +cSpell:ignore: taxo --- -Docsy supports Hugo's Taxonomies (see: https://gohugo.io/content-management/taxonomies/) in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page. +Docsy supports Hugo [taxonomies] in its docs and blog section. You can see the +default layout and can test the behavior of the generated links on this page. ## Terminology -To understand the usage of taxonomies you should understand the following terminology: +To understand the usage of taxonomies you should understand the following +terminology: -Taxonomy -: a categorization that can be used to classify content - e.g.: Tags, Categories, Projects, People +- **Taxonomy**: a categorization that can be used to classify content - e.g.: + Tags, Categories, Projects, People -Term -: a key within the taxonomy - e.g. within projects: Project A, Project B +- **Term**: a key within the taxonomy - e.g. within projects: Project A, Project + B -Value -: a piece of content assigned to a term - e.g. a page of your site, that belongs to a specific project +- **Value**: a piece of content assigned to a term - e.g. a page of your site, + that belongs to a specific project -A example taxonomy for a movie website you can find in the official Hugo docs: https://gohugo.io/content-management/taxonomies/#example-taxonomy-movie-website +A [movie-website sample][] taxonomy is provided by the Hugo docs. -## Parameters +[movie-website sample]: + https://gohugo.io/content-management/taxonomies/#example-taxonomy-movie-website -There are various parameter to control the functionality of taxonomies in the project [configuration file]. +## Parameters -By default taxonomies for `tags` and `categories` are enabled in Hugo (see: https://gohugo.io/content-management/taxonomies/#default-taxonomies). In Docsy taxonomies are __disabled__ by default in the `hugo.toml`/`hugo.yaml`/`hugo.json`: +There are various parameter to control the functionality of taxonomies in the +project [configuration file][]. Taxonomies are [enabled by default][] for `tags` +and `categories` in Hugo. To **disable** taxonomies, add the following to your +project config: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} -disableKinds = ["taxonomy", "taxonomyTerm"] +disableKinds = ["taxonomy"] {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -disableKinds: - - taxonomy - - taxonomyTerm +disableKinds: [taxonomy] {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "disableKinds": [ - "taxonomy", - "taxonomyTerm" - ] + "disableKinds": [ "taxonomy" ] } {{< /tab >}} {{< /tabpane >}} + -If you want to enable taxonomies in Docsy you have to delete (or comment out) this line in your project's `hugo.toml`/`hugo.yaml`/`hugo.json`. Then the taxonomy pages for `tags` and `categories` will be generated by Hugo. If you want to use other taxonomies you have to define them in your [configuration file]. If you want to use beside your own taxonomies also the default taxonomies `tags` and `categories`, you also have to define them beside your own taxonomies. You need to provide both the plural and singular labels for each taxonomy. +Then the taxonomy pages for `tags` and `categories` will be generated by Hugo. +If you want to use other taxonomies you have to define them in your +[configuration file]. If you want to use beside your own taxonomies also the +default taxonomies `tags` and `categories`, you also have to define them beside +your own taxonomies. You need to provide both the plural and singular labels for +each taxonomy. -With the following example you define a additional taxonomy `projects` beside the default taxonomies `tags` and `categories`: +With the following example you define a additional taxonomy `projects` beside +the default taxonomies `tags` and `categories`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -79,9 +89,13 @@ taxonomies: } {{< /tab >}} {{< /tabpane >}} + -You can use the following parameters in your project's `hugo.toml`/`hugo.yaml`/`hugo.json` to control the output of the assigned taxonomy terms for each article resp. page of your docs and/or blog section in Docsy or a "tag cloud" in Docsy's right sidebar: +You can use the following parameters in your project's config to control the +output of the assigned taxonomy terms for each article resp. page of your docs +and/or blog section in Docsy or a "tag cloud" in Docsy's right sidebar: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -124,23 +138,38 @@ params: } {{< /tab >}} {{< /tabpane >}} + + +The settings above would only show a taxonomy cloud for `projects` and `tags` +(with the headlines "Our Projects" and "Tag Cloud") in Docsy's right sidebar and +the assigned terms for the taxonomies `tags` and `categories` for each page. -The settings above would only show a taxonomy cloud for `projects` and `tags` (with the headlines "Our Projects" and "Tag Cloud") in Docsy's right sidebar and the assigned terms for the taxonomies `tags` and `categories` for each page. +To disable any taxonomy cloud you have to set the Parameter `taxonomyCloud = []` +resp. if you don't want to show the assigned terms you have to set +`taxonomyPageHeader = []`. -To disable any taxonomy cloud you have to set the Parameter `taxonomyCloud = []` resp. if you don't want to show the assigned terms you have to set `taxonomyPageHeader = []`. +As default the plural label of a taxonomy is used as it cloud title. You can +overwrite the default cloud title with `taxonomyCloudTitle`. But if you do so, +you have to define a manual title for each enabled taxonomy cloud +(`taxonomyCloud` and `taxonomyCloudTitle` must have the same length!). -As default the plural label of a taxonomy is used as it cloud title. You can overwrite the default cloud title with `taxonomyCloudTitle`. But if you do so, you have to define a manual title for each enabled taxonomy cloud (`taxonomyCloud` and `taxonomyCloudTitle` must have the same length!). +If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the +taxonomy clouds resp. assigned terms for all defined taxonomies will be +generated. -If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the taxonomy clouds resp. assigned terms for all defined taxonomies will be generated. ## Partials -The by default used partials for displaying taxonomies are so defined, that you should be able to use them also easily in your own layouts. +The by default used partials for displaying taxonomies are so defined, that you +should be able to use them also easily in your own layouts. ### taxonomy_terms_article -The partial `taxonomy_terms_article` shows all assigned terms of an given taxonomy (partial parameter `taxo`) of an article respectively page (partial parameter `context`, most of the time the current page or context `.`). +The partial `taxonomy_terms_article` shows all assigned terms of an given +taxonomy (partial parameter `taxo`) of an article respectively page (partial +parameter `context`, most of the time the current page or context `.`). -Example usage in `layouts/docs/list.html` for the header of each page in the docs section: +Example usage in `layouts/docs/list.html` for the header of each page in the +docs section: ```go-html-template {{ $context := . }} @@ -149,33 +178,72 @@ Example usage in `layouts/docs/list.html` for the header of each page in the doc {{ end }} ``` -This will gave you for each in the current page (resp. context) defined taxonomy a list with all assigned terms: +This will gave you for each in the current page (resp. context) defined taxonomy +a list with all assigned terms: + ```html
Categories:
Tags:
``` ### taxonomy_terms_article_wrapper -The partial `taxonomy_terms_article_wrapper` is a wrapper for the partial `taxonomy_terms_article` with the only parameter `context` (most of the time the current page or context `.`) and checks the taxonomy parameters of your project's `hugo.toml`/`hugo.yaml`/`hugo.json` to loop threw all listed taxonomies in the parameter `taxonomyPageHeader` resp. all defined taxonomies of your page, if `taxonomyPageHeader` isn't set. +The partial `taxonomy_terms_article_wrapper` is a wrapper for the partial +`taxonomy_terms_article` with the only parameter `context` (most of the time the +current page or context `.`) and checks the taxonomy parameters of your +project's `hugo.toml`/`hugo.yaml`/`hugo.json` to loop threw all listed +taxonomies in the parameter `taxonomyPageHeader` resp. all defined taxonomies of +your page, if `taxonomyPageHeader` isn't set. ### taxonomy_terms_cloud -The partial `taxonomy_terms_cloud` shows all used terms of an given taxonomy (partial parameter `taxo`) for your site (partial parameter `context`, most of the time the current page or context `.`) and with the parameter `title` as headline. +The partial `taxonomy_terms_cloud` shows all used terms of an given taxonomy +(partial parameter `taxo`) for your site (partial parameter `context`, most of +the time the current page or context `.`) and with the parameter `title` as +headline. -Example usage in partial `taxonomy_terms_clouds` for showing all defined taxonomies and its terms: +Example usage in partial `taxonomy_terms_clouds` for showing all defined +taxonomies and its terms: ```go-html-template {{ $context := . }} @@ -184,25 +252,69 @@ Example usage in partial `taxonomy_terms_clouds` for showing all defined taxonom {{ end }} ``` -As an example this will gave you for following HTML markup for the taxonomy `categories`: +This will give you the following HTML markup for the taxonomy `categories`: + ```html
Cloud of Categories
``` ### taxonomy_terms_clouds -The partial `taxonomy_terms_clouds` is a wrapper for the partial `taxonomy_terms_cloud` with the only parameter `context` (most of the time the current page or context `.`) and checks the taxonomy parameters of your project's `hugo.toml`/`hugo.yaml`/`hugo.json` to loop threw all listed taxonomies in the parameter `taxonomyCloud` resp. all defined taxonomies of your page, if `taxonomyCloud` isn't set. +The partial `taxonomy_terms_clouds` is a wrapper for the partial +`taxonomy_terms_cloud` with the only parameter `context` (most of the time the +current page or context `.`) and checks the taxonomy parameters of your +project's config to loop threw all listed taxonomies in the parameter +`taxonomyCloud` resp. all defined taxonomies of your page, if `taxonomyCloud` +isn't set. ## Multi language support for taxonomies -The taxonomy terms associated content gets only counted and linked WITHIN the language! The control parameters for the taxonomy support can also get assigned language specific. +For [multilingual sites][], taxonomy terms get counted and linked _within_ the +language site only. Taxonomy config parameters can be adjusted per language. -[configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file \ No newline at end of file +[configuration file]: + https://gohugo.io/getting-started/configuration/#configuration-file +[enabled by default]: + https://gohugo.io/content-management/taxonomies/#default-destinations +[multilingual sites]: https://gohugo.io/configuration/params/#multilingual-sites +[taxonomies]: https://gohugo.io/content-management/taxonomies/ diff --git a/userguide/content/en/docs/adding-content/versioning.md b/userguide/content/en/docs/adding-content/versioning.md index a7852d75a8..da6140635e 100644 --- a/userguide/content/en/docs/adding-content/versioning.md +++ b/userguide/content/en/docs/adding-content/versioning.md @@ -1,23 +1,25 @@ --- -title: "Doc Versioning" +title: Doc Versioning date: 2020-02-02 weight: 4 -description: > - Customize navigation and banners for multiple versions of your docs. +description: >- + Customize navigation and banners for multiple versions of your docs. --- Depending on your project's releases and versioning, you may want to let your users access previous versions of your documentation. How you deploy the previous versions is up to you. This page describes the Docsy features that you -can use to provide navigation between the various versions of your docs and -to display an information banner on the archived sites. +can use to provide navigation between the various versions of your docs and to +display an information banner on the archived sites. ## Adding a version drop-down menu -If you add some `[params.versions]` in `hugo.toml`/`hugo.yaml`/`hugo.json`, the Docsy theme adds a -version selector drop down to the top-level menu. You specify a URL and a name -for each version you would like to add to the menu, as in the following example: +If you add some `[params.versions]` in `hugo.toml`/`hugo.yaml`/`hugo.json`, the +Docsy theme adds a version selector drop down to the top-level menu. You specify +a URL and a name for each version you would like to add to the menu, as in the +following example: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -65,12 +67,15 @@ params: } {{< /tab >}} {{< /tabpane >}} + Remember to add your current version so that users can navigate back! The default title for the version drop-down menu is **Releases**. To change the -title, change the site parameter `version_menu` in `hugo.toml`/`hugo.yaml`/`hugo.json`: +title, change the site parameter `version_menu` in +`hugo.toml`/`hugo.yaml`/`hugo.json`: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -89,11 +94,13 @@ params: } {{< /tab >}} {{< /tabpane >}} + -If you set the `version_menu_pagelinks` parameter to `true`, then links in the version drop-down menu -point to the current page in the other version, instead of the main page. -This can be useful if the document doesn't change much between the different versions. -Note that if the current page doesn't exist in the other version, the link will be broken. +If you set the `version_menu_pagelinks` parameter to `true`, then links in the +version drop-down menu point to the current page in the other version, instead +of the main page. This can be useful if the document doesn't change much between +the different versions. Note that if the current page doesn't exist in the other +version, the link will be broken. You can read more about Docsy menus in the guide to [navigation and search](/docs/adding-content/navigation/). @@ -119,6 +126,8 @@ For example, see the archived docs for To add the banner to your doc site, make the following changes in your `hugo.toml`/`hugo.yaml`/`hugo.json` file: + + 1. Set the site parameter `archived_version` to `true`: {{< tabpane >}} @@ -184,3 +193,5 @@ params: } {{< /tab >}} {{< /tabpane >}} + + diff --git a/userguide/content/en/docs/best-practices/site-guidance.md b/userguide/content/en/docs/best-practices/site-guidance.md index 12a3ae65de..baca15a9e1 100644 --- a/userguide/content/en/docs/best-practices/site-guidance.md +++ b/userguide/content/en/docs/best-practices/site-guidance.md @@ -1,21 +1,29 @@ --- -title: "Hugo Content Tips" -linkTitle: "Hugo Content Tips" +title: Hugo Content Tips weight: 9 -description: > - Tips for authoring content for your Docsy-themed Hugo site. +description: Tips for authoring content for your Docsy-themed Hugo site. --- -Docsy is a theme for the [Hugo](https://gohugo.io/) static site generator. -If you're not already familiar with Hugo this page provides some useful tips and -potential gotchas for adding and editing content for your site. Feel free to add your own! +Docsy is a theme for the [Hugo](https://gohugo.io/) static site generator. If +you're not already familiar with Hugo this page provides some useful tips and +potential gotchas for adding and editing content for your site. Feel free to add +your own! ## Linking -By default, regular relative URLs in links are left unchanged by Hugo (they're still relative links in your site's generated HTML), hence some hardcoded relative links like `[relative cross-link](../../peer-folder/sub-file.md)` might behave unexpectedly compared to how they work on your local file system. You may find it helpful to use some of Hugo's built-in [link shortcodes](https://gohugo.io/content-management/cross-references/#use-ref-and-relref) to avoid broken links in your generated site. For example a `{{}}` link in Hugo will actually -find and automatically link to your file named `filename.md`. +By default, regular relative URLs in links are left unchanged by Hugo (they're +still relative links in your site's generated HTML), hence some hardcoded +relative links like `[relative cross-link](../../peer-folder/sub-file.md)` might +behave unexpectedly compared to how they work on your local file system. You may +find it helpful to use some of Hugo's built-in link shortcodes like +[relref](https://gohugo.io/shortcodes/relref/) to avoid broken links in your +generated site. For example a `{{}}` link in Hugo will +actually find and automatically link to your file named `filename.md`. -Note, however, that `ref` and `relref` links don't work with `_index` or `index` files (for example, this site's [content landing page](/docs/adding-content/)): you'll need to use regular Markdown links to section landing or other index pages. Specify these links relative to the site's root URL, for example: `/docs/adding-content/`. +Note, however, that `ref` and `relref` links don't work with `_index` or `index` +files (for example, this site's [content landing page](/docs/adding-content/)): +you'll need to use regular Markdown links to section landing or other index +pages. Specify these links relative to the site's root URL, for example: +`/docs/adding-content/`. [Learn more about linking](/docs/adding-content/content/#working-with-links). - diff --git a/userguide/content/en/docs/contribution-guidelines/_index.md b/userguide/content/en/docs/contribution-guidelines/_index.md index f765d8ff0f..0c182d0421 100644 --- a/userguide/content/en/docs/contribution-guidelines/_index.md +++ b/userguide/content/en/docs/contribution-guidelines/_index.md @@ -73,7 +73,6 @@ If you've just spotted something you'd like to change while using the docs, Docs 1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode. 1. Follow the rest of the [Quick start with Netlify](#quick-start-with-netlify) process above to make and preview your changes. - ### Previewing your changes locally If you want to run your own local Hugo server to preview your changes as you work: @@ -93,7 +92,9 @@ If you want to run your own local Hugo server to preview your changes as you wor hugo server --themesDir ../.. ``` - By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site. + By default your site will be available at . Now that + you're serving your site locally, Hugo will watch for changes to the content + and automatically refresh your site. 1. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request. @@ -133,7 +134,7 @@ locally with Docker, without installing any additional dependencies. DOCSY_USER=$(id -u):$(id -g) docker-compose up ``` -Open `http://localhost:1313` in your web browser to load the docsy user guide. +Open in your web browser to load the docsy user guide. In most cases, docsy will automatically reload the site to reflect any changes to the documentation or the code. Changes to some parts of the docsy code may require manually reloading the page or re-starting the container. @@ -143,8 +144,39 @@ Press **Ctrl + C** to stop the container. [docker]: https://docs.docker.com/get-docker/ [docker-compose]: https://docs.docker.com/compose/install/ -### Creating an issue +### User guide formatting + +We use [Prettier](https://prettier.io) to format the markdown source of the User +Guide. To to check the formatting of your documentation changes, use the +following command: + +```bash +npm run check:format +``` -If there's something you'd like to see in the docs, but you're not sure how to fix it yourself, please create an issue in [this repository](https://github.com/google/docsy). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page. +To automatically fix formatting issues, run `npm run fix:format`. +Prettier doesn't currently understand Hugo template language directives, +so you might need to bracket such directives using the following ignore +directives: + +```go-html-template + +{{}} +... +{{}} + +``` + +You can use these ignore directives to surround any markdown that you'd like +Prettier to ignore. If the region is a contiguous block of text, then you can +omit the end directive and replace the start directive with +`prettier-ignore-start`. + +### Creating an issue +If there's something you'd like to see in the docs, but you're not sure how to +fix it yourself, please create an issue in [this +repository](https://github.com/google/docsy). You can also create an issue about +a specific page by clicking the **Create Issue** button in the top right hand +corner of the page. diff --git a/userguide/content/en/docs/deployment/_index.md b/userguide/content/en/docs/deployment/_index.md index 63a278dcbf..7d87275c83 100644 --- a/userguide/content/en/docs/deployment/_index.md +++ b/userguide/content/en/docs/deployment/_index.md @@ -45,9 +45,11 @@ Then follow the instructions in [Host on Netlify](https://gohugo.io/hosting-and- * If you are using Docsy as a [Hugo module](/docs/get-started/docsy-as-module/) or NPM package, you can just specify `hugo`. 3. Click **Show advanced**. 4. In the **Advanced build settings** section, click **New variable**. - 5. Specify `HUGO_VERSION` as the **Key** for the new variable, and set its **Value** to the latest version of Hugo (minimum required version: `0.110.0`). - 6. In the **Advanced build settings** section, click **New variable** again. - 7. Specify `GO_VERSION` as the **Key** for the new variable, and set its **Value** to the latest version of Go (minimum recommended version: `1.18`). + 5. Specify `NODE_VERSION` as the **Key** for the new variable, and set its **Value** to the [latest LTS version](https://nodejs.org/en/download/) of Node.js. + 6. In the **Advanced build settings** section, click **New variable**. + 7. Specify `HUGO_VERSION` as the **Key** for the new variable, and set its **Value** to the [latest version](https://github.com/gohugoio/hugo/releases) of Hugo. + 8. In the **Advanced build settings** section, click **New variable** again. + 9. Specify `GO_VERSION` as the **Key** for the new variable, and set its **Value** to the [latest version](https://go.dev/dl/) of Go. If you don't want your site to be indexed by search engines, you can add an environment flag to your build command to specify a non-`production` environment, as described in [Build environments and indexing](#build-environments-and-indexing). 1. Click **Deploy site**. @@ -59,9 +61,9 @@ For example, if you want to use a version of `postcss-cli` later than version 8. ``` "devDependencies": { - "autoprefixer": "^9.8.8", - "postcss-cli": "^8.0.0", - "postcss": "^8.0.0" + "autoprefixer": "^10.4.19", + "postcss-cli": "^11.0.0", + "postcss": "^8.4.38" } ``` @@ -71,9 +73,141 @@ Alternatively, you can follow the same instructions but specify your **Deploy se If you have an existing deployment you can view and update the relevant information by selecting the site from your list of sites in Netlify, then clicking **Site settings** - **Build and deploy**. Ensure that **Ubuntu Focal 20.04** is selected in the **Build image selection** section - if you're creating a new deployment this is used by default. You need to use this image to run the extended version of Hugo. +## Deployment on GitHub Pages + +If your repo is hosted on [GitHub](https://github.com), a simple option is to serve your site with [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages). GitHub Pages lets you create project, user, and organization sites; for a project site, your site URL will be `http(s)://.github.io/`, custom domains are also supported. GitHub Pages come with [continuous deployment](https://docs.github.com/en/actions/deployment/about-deployments/about-continuous-deployment) using GitHub actions, while the [marketplace for actions](https://github.com/marketplace?no-link-check&type=actions) has useful tools for spell and link checking, deploy previews, and more. Using your existing GitHub account, you can start by using the free plan for publicly available repositories, with premium tiers available for business use cases. + +The Docsy example site repo provides a [workflow file](https://github.com/google/docsy-example/blob/master/.github/workflows/deploy-github-pages.yml?no-link-check) that you can use when deploying to GitHub Pages. If you used the example site as template for your new site as described [here](https://www.docsy.dev/docs/get-started/docsy-as-module/example-site-as-template/), you may already have this file in your repo, if not the instructions below show you how to create your own workflow file. + +Before deploying on GitHub Pages, make sure that you've pushed your site source to your chosen GitHub repo, following any setup instructions in [Using the theme](/docs/get-started/docsy-as-module). + +{{% alert title="Correct baseURL setting" color="primary" %}} +Make sure to correctly set your site's `baseURL`, either via hugo's `--baseURL '…'` command line parameter or inside your your `hugo.toml`/`hugo.yaml`/`hugo.json` configuration file. When deploying to GitHub pages your `baseURL` needs to be set to `https://.github.io/`, otherwise your site layout will be broken. +{{% /alert %}} + +1. With GitHub Pages, a site is published to the branch `gh-pages` and served from there by default. You must create this branch first, either in the GitHub web interface or via command line (at the root of your local repo clone): + + ```console + $ git checkout -b gh-pages + Switched to a new branch 'gh-pages' + ``` + +1. Push this local branch to your repo: + + ```console + $ git push --set-upstream origin gh-pages + details omitted … + * [new branch] new -> new + branch 'gh-pages' set up to track 'origin/gh-pages'. + ``` + +1. Switch back to the `main` (or `work`) branch of your repo: + + ```console + $ git checkout main + Switched to branch 'main' + + ``` + +1. Check if you already have the workflow file `.github/workflows/deploy-github-pages.yml` in your repo. If this file doesn't exist, do the following: + + 1. Create a new empty workflow file from the root of your repo, as follows: + + ```console + $ mkdir -p .github/workflows + $ touch .github/workflows/deploy-github-pages.yml + ``` + + + 1. Open the file in an editor of your choice, paste in the code below, and save the file: + + ```yaml + name: Deployment to GitHub Pages + + on: + workflow_dispatch: + push: + branches: + - main # <-- specify the branch you want to deploy from + pull_request: + + env: + REPO_NAME: ${{ github.event.repository.name }} + REPO_OWNER: ${{ github.repository_owner }} + + jobs: + deploy: + runs-on: ubuntu-22.04 + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + + - name: Setup Hugo + uses: peaceiris/actions-hugo@v3 + with: + hugo-version: '0.125.5' + extended: true + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: '**/package-lock.json' + + - run: npm ci + - run: hugo --baseURL https://${REPO_OWNER}.github.io/${REPO_NAME} --minify + + - name: Deploy + uses: peaceiris/actions-gh-pages@v4 + if: ${{ github.ref == 'refs/heads/main' }} # <-- specify same branch as above here + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + ``` + + 1. Add the file to the staging area, commit your change and push the change to your remote GitHub repo: + + ```console + $ git add .github/workflows/deploy-github-pages.yml + $ git commit -m "Adding workflow file for site deployment" + $ git push origin + ``` + +1. In your browser, make sure you are logged into your GitHub account. In your repo **Settings**, select **Pages**. + + 1. Under **Build and deployment**, select **Deploy from a branch** in the **source** dropdown. + + 2. From the **branch** dropdown, select **gh-pages** as branch where the site is built from. + + 3. From the **folder** dropdown, select **/(root)** as root directory. + +That's it! Your deployment workflow for your site is configured. + +Any future push to the branch specified in your workflow file will now trigger the action workflow defined in the workflow file. Additionally, you can trigger the deployment manually by using GitHub web UI. + +Once you push to your repo, you can see the progress of the triggered workflow in the **Actions** tab of the the GitHub web UI: + +``` +URL 'Repo actions': https://github.com///actions +``` + +After the first successful deployment, a new environment `github-pages` is added to your repo. This is shown at the right of your repo main view (below **Releases** and **Packages**). When you click on this environment, a list of deployments is displayed: + +``` +URL 'Repo deployments': https://github.com///deployments/ +``` + +You can find out more in [Hosting on GitHub]( https://gohugo.io/hosting-and-deployment/hosting-on-github/) in the Hugo documentation. + +For advanced use cases, the [`hugo-action`](https://github.com/peaceiris/actions-hugo) used inside the workflow file has more configuration options, which are well [documented](https://github.com/marketplace/actions/hugo-setup). + + ## Deployment with Amazon S3 + Amazon CloudFront -There are several options for publishing your web site using [Amazon Web Services](https://aws.amazon.com), as described in this [blog post](https://adrianhall.github.io/cloud/2019/01/31/which-aws-service-for-hosting/). This section describes the most basic option, deploying your site using an S3 bucket and activating the CloudFront CDN (content delivery network) to speed up the delivery of your deployed contents. +There are several options for publishing your web site using [Amazon Web Services](https://aws.amazon.com). This section describes the most basic option, deploying your site using an S3 bucket and activating the CloudFront CDN (content delivery network) to speed up the delivery of your deployed contents. 1. After your [registration](https://portal.aws.amazon.com/billing/signup#/start) at AWS, create your S3 bucket, connect it with your domain, and add it to the CloudFront CDN. This [blog post](https://www.noorix.com.au/blog/how-to/hosting-static-website-with-aws-s3-cloudfront/) has all the details and provides easy to follow step-by-step instructions for the whole procedure. 1. Download and install the latest version 2 of the AWS [Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/get-started-install.html) (CLI). Then configure your CLI instance by issuing the command `aws configure` (make sure you have your AWS Access Key ID and your AWS Secret Access Key at hand): @@ -117,7 +251,8 @@ deployment: } ] } -}{{< /tab >}} +} +{{< /tab >}} {{< /tabpane >}} 1. Run the command `hugo --gc --minify` to render the site's assets into the `public/` directory of your Hugo build environment. diff --git a/userguide/content/en/docs/examples/_index.md b/userguide/content/en/docs/examples/_index.md index 01d633d7ce..25a8b52c09 100644 --- a/userguide/content/en/docs/examples/_index.md +++ b/userguide/content/en/docs/examples/_index.md @@ -16,7 +16,6 @@ Example sites that have low to no customization: | ["Goldydocs" - a Docsy example site](https://example.docsy.dev) | https://github.com/google/docsy-example | | https://www.kubeflow.org/ | https://github.com/kubeflow/website | | https://agones.dev/site/ | https://github.com/googleforgames/agones/tree/main/site | -| https://googlecontainertools.github.io/kpt/ | https://github.com/GoogleContainerTools/kpt/tree/main/docs | | [Navidrome Music Server](https://www.navidrome.org) | https://github.com/navidrome/website | | https://docs.agilebase.co.uk/ | https://github.com/okohll/abdocs | | https://jvmperf.net/ | https://github.com/cchesser/java-perf-workshop | @@ -24,7 +23,6 @@ Example sites that have low to no customization: | [tekton.dev](https://tekton.dev/) | https://github.com/tektoncd | | [fluxcd.io](https://fluxcd.io) | https://github.com/fluxcd/website | | [Graphviz](https://graphviz.org) | https://gitlab.com/graphviz/graphviz.gitlab.io | -| [Cloudpods](https://www.cloudpods.org) | https://github.com/yunionio/docs | | [Selenium](https://www.selenium.dev/) | https://github.com/SeleniumHQ/seleniumhq.github.io | | [fission.io](https://fission.io/) | https://github.com/fission/fission.io | | [Stroom](https://gchq.github.io/stroom-docs) | https://github.com/gchq/stroom-docs | @@ -34,6 +32,7 @@ Example sites that have low to no customization: | [protobuf.dev](https://protobuf.dev) | https://github.com/protocolbuffers/protocolbuffers.github.io | | [Layer5 Docs](https://docs.layer5.io/) | https://github.com/layer5io/docs | | [Apache Parquet](https://parquet.apache.org/) | https://parquet.apache.org | +| [YMCA Website Services](https://ds-docs.y.org/) | https://github.com/YCloudYUSA/yusaopeny_docs | ## Customized Docsy examples diff --git a/userguide/content/en/docs/get-started/basic-configuration.md b/userguide/content/en/docs/get-started/basic-configuration.md index dc8125c274..bc41677a6c 100644 --- a/userguide/content/en/docs/get-started/basic-configuration.md +++ b/userguide/content/en/docs/get-started/basic-configuration.md @@ -7,7 +7,7 @@ description: > Basic configuration for new Docsy sites. --- -Site-wide configuration details and parameters are defined in your project's [configuration file] (`hugo.toml` or `config.toml`). These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`hugo.toml` in the example project](https://github.com/google/docsy-example/blob/main/hugo.toml) for how to add this information. **We recommend copying this hugo.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site**, as it includes default values for many parameters that you need to set for your site to build correctly. +Site-wide configuration details and parameters are defined in your project's [configuration file] (`hugo.toml` or `config.toml`). These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`hugo.yaml` in the example project](https://github.com/google/docsy-example/blob/main/hugo.yaml) for how to add this information. **We recommend copying this hugo.yaml and editing it even if you’re just using the theme and not copying the entire Docsy example site**, as it includes default values for many parameters that you need to set for your site to build correctly. You may want to remove or customize some defaults of the copied `hugo.toml` file straight away: diff --git a/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md b/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md index 1c0bc37cce..52d83de7bd 100644 --- a/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md +++ b/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md @@ -10,7 +10,7 @@ This page describes the prerequisites for building a site that uses Docsy as a H ## Install Hugo -You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (version 0.110.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. +You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (version 0.146.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io). @@ -70,7 +70,7 @@ Hugo's commands for module management require that the Go programming language i ```console $ go version -go version go1.21.6 +go version go1.24.3 ``` Ensure that you are using version 1.12 or higher. @@ -84,7 +84,7 @@ Hugo's commands for module management require that the `git` client is installed ```console $ git version -git version 2.43.0 +git version 2.49.0 ``` If no `git` client is installed on your system yet, go to the [Git website](https://git-scm.com/), download the installer for your system architecture and execute it. Afterwards, check for a successful installation. @@ -138,11 +138,11 @@ You can check your current Node.js version by running `node -v`. If you need to ```bash # Using Ubuntu - curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - + curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs # Using Debian, as root - curl -fsSL https://deb.nodesource.com/setup_20.x | bash - + curl -fsSL https://deb.nodesource.com/setup_22.x | bash - apt-get install -y nodejs ``` @@ -152,10 +152,10 @@ You can check your current Node.js version by running `node -v`. If you need to ```bash # As root - curl -fsSL https://rpm.nodesource.com/setup_20.x | bash - + curl -fsSL https://rpm.nodesource.com/setup_22.x | bash - # No root privileges - curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - + curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - ``` diff --git a/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md b/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md index 5ed5bd876b..6b43d65cf2 100644 --- a/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md +++ b/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md @@ -55,7 +55,7 @@ Specifying the [Docsy theme](https://github.com/google/docsy) as Hugo Module for ### Create your new skeleton project -To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project's root directory. +To create a new Hugo site project and then add the Docsy theme as a Hugo module, run the following commands from your project's root directory. ```bash hugo new site my-new-site diff --git a/userguide/content/en/docs/get-started/other-options.md b/userguide/content/en/docs/get-started/other-options.md index b7729c8f22..10fd6c7403 100644 --- a/userguide/content/en/docs/get-started/other-options.md +++ b/userguide/content/en/docs/get-started/other-options.md @@ -2,7 +2,7 @@ title: Other setup options description: Create a new Docsy site with Docsy using Git or NPM date: 2021-12-08T09:22:27+01:00 -spelling: cSpell:ignore docsy gohugo hugo myproject +cSpell:ignore: docsy gohugo hugo myproject weight: 2 --- @@ -66,6 +66,7 @@ The following shows you how to install Hugo from the release page: 3. Download the latest extended version (`hugo_extended_0.9X_Linux-64bit.tar.gz`). 4. Create a new directory: + ```sh mkdir hugo ``` @@ -73,6 +74,7 @@ The following shows you how to install Hugo from the release page: 5. Extract the files you downloaded to `hugo`. 6. Switch to your new directory: + ```sh cd hugo ``` @@ -105,9 +107,8 @@ If you have Node installed already, check your version of Node. For example: node -v ``` -Install or upgrade your version of Node to the **active [LTS release][]**. We -recommend using **[nvm][]** to manage your Node installation (Linux command -shown): +Install or upgrade your version of Node to the **active [LTS release][]**. We recommend +using **[nvm][]** to manage your Node installation (Linux command shown): ```sh nvm install --lts @@ -122,9 +123,8 @@ To build or update your site's CSS resources, you'll also need {{% alert title="IMPORTANT: Check your Node version" color="warning" %}} The PostCSS package installed by some older versions of Node is incompatible -with Docsy. Check your version of Node against the **active [LTS release][]** -and upgrade, if necessary. For details, see [Node: Get the latest LTS -release][latest-lts]. +with Docsy. Check your version of Node against the **active [LTS release][]** and +upgrade, if necessary. For details, see [Node: Get the latest LTS release][latest-lts]. [lts release]: https://nodejs.org/en/about/releases/ [latest-lts]: #node-get-the-latest-lts-release @@ -169,8 +169,8 @@ your project's root directory: git checkout v{{% param version %}} ``` - To work from the development version of Docsy (not recommended), - run the following command instead: + To work from the development version of Docsy (_not recommended_), run the + following command instead: ```sh git submodule add --depth 1 https://github.com/google/docsy.git themes/docsy @@ -179,12 +179,12 @@ your project's root directory: 2. Add Docsy as a theme, for example: ```sh - echo 'theme = "docsy"' >> hugo.toml + echo 'theme: docsy' >> hugo.yaml ``` - {{% alert title="Tip" %}} -In Hugo 0.110.0 the default config base filename was changed to `hugo.toml`. -If you are using hugo 0.110 or above, consider renaming your `config.toml` to `hugo.toml`! + {{% alert title="Tip" %}}As of Hugo 0.110.0, the default config base + filename was changed to `hugo.*` from `config.*`. If you are using hugo + 0.110 or above, consider renaming your `config.*` to `hugo.*`. {{% /alert %}} 3. Get Docsy dependencies: @@ -242,8 +242,8 @@ npm install > **Important**: read the [Docsy NPM install side-effect] note. To work from the development version of Docsy (not recommended unless, for -example, you plan to upstream changes to Docsy), omit the `-b v{{% param version -%}}` argument from the clone command above. +example, you plan to upstream changes to Docsy), omit the +`-b v{{% param version %}}` argument from the clone command above. Then consider setting up an NPM [prepare][] script, as documented in Option 1. @@ -258,14 +258,15 @@ You can use Docsy as an NPM module as follows: 1. Create your site and specify Docsy as the site theme: ```sh - hugo new site myproject + hugo new site --format yaml myproject cd myproject - echo 'theme = "docsy"' >> hugo.toml + echo "theme: docsy\nthemesDir: node_modules" >> hugo.yaml ``` 2. Install Docsy, and postCSS (as [instructed earlier](#install-postcss)): ```console + npm init -y npm install --save-dev google/docsy#semver:{{% param version %}} autoprefixer postcss-cli ``` @@ -275,18 +276,28 @@ You can use Docsy as an NPM module as follows: path to the Docsy theme files. For example, build your site as follows: ```console - $ hugo --themesDir node_modules + $ hugo Start building sites … ... - Total in 1890 ms ``` - You can drop the `--themesDir ...` flag by adding the themes directory to - your site's configuration file: + {{% alert title="Error: failed to load modules" color="warning" %}} - ```sh - echo 'themesDir = "node_modules"' >> hugo.toml - ``` +If Hugo reports the following error when building your site ([#2116]): + +``` +Error: failed to load modules: module "github.com/FortAwesome/Font-Awesome" not found in ".../myproject/node_modules/github.com/FortAwesome/Font-Awesome" ... +``` + +Then run the following command and try again: + +```sh +npm rebuild +``` + +[#2116]: https://github.com/google/docsy/issues/2116 + +{{% /alert %}} As an alternative to specifying a `themesDir`, on some platforms, you can instead create a symbolic link to the Docsy theme directory as follows (Linux @@ -312,7 +323,10 @@ docsy github.com ``` This is a workaround necessary to support Docsy's use as a single [Hugo module] -([#1120]). +([#1120]) in the context of projects _not_ using Hugo modules. The `github.com` +folder is created via Docsy's `postinstall` script. To disable this behavior, +set the environment variable `DOCSY_MKDIR_HUGO_MOD_SKIP=1` before running NPM +install. [#1120]: https://github.com/google/docsy/issues/1120 [0.8.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#080 diff --git a/userguide/content/en/docs/language/_index.md b/userguide/content/en/docs/language/_index.md index a839063b2b..6c11c411ce 100644 --- a/userguide/content/en/docs/language/_index.md +++ b/userguide/content/en/docs/language/_index.md @@ -1,17 +1,23 @@ --- -title: "Multi-language Support" -linkTitle: "Multi-language Support" +title: Multi-language Support weight: 7 -description: > - Support multiple languages in your site. +description: Support multiple languages in your site. +cSpell:ignore: Goldydocs rtlcss subdir operativsystem skyen Norsk --- -If you'd like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions. +If you'd like to provide site content in multiple languages, the Docsy theme and +Hugo make it easy to both add your translated content and for your users to +navigate between language versions. ## Content and configuration -To add content in multiple languages, you first need to define the available languages in a `languages` section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English: +To add content in multiple languages, you first need to define the available +languages in a `languages` section in your site configuration. Each language can +have its own language-specific configuration. For example, the [Docsy example] +site config specifies that it provides content in English, Norwegian, and +Persian. The default language is English: + {{< tabpane >}} {{< tab header="Configuration file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} @@ -85,35 +91,96 @@ languages: } {{< /tab >}} {{< /tabpane >}} + -Any setting not defined in a `[languages]` block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be `content/en` unless the user selects the Norwegian language option. +Any setting not defined in a `[languages]` block will fall back to the global +value for that setting: so, for example, the content directory used for the site +above will be `content/en` unless the user selects the Norwegian language +option. -Once you've updated your site config, you create a content root directory for each language version in your source repo, such as `content/en` for English text, and add your [content](/docs/adding-content/content/) as usual. See the [Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language support for more information. +Once you've updated your site config, you create a content root directory for +each language version in your source repo, such as `content/en` for English +text, and add your [content](/docs/adding-content/content/) as usual. See the +[Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language +support for more information. + +{{% alert title="Attention (only when using Docsy as hugo module)" color="warning" %}} + +If you have a multi language installation, ensure that the section `[languages]` +inside your +[configuration file](https://gohugo.io/getting-started/configuration/#configuration-file) +is declared **before** the section `[module]` with the module imports. Otherwise +you will run into trouble! -{{% alert title="Attention (only when using docsy as hugo module)" color="warning" %}} -If you have a multi language installation, please make sure that the section `[languages]` inside your [configuration file](https://gohugo.io/getting-started/configuration/#configuration-file) is declared **before** the section `[module]` with the module imports. Otherwise you will run into trouble! {{% /alert %}} {{% alert title="Tip" %}} -If there's any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don't need to move it if you add another language. + +If there's any possibility your site might be translated into other languages, +consider creating your site with your content in a language-specific +subdirectory, as it means you don't need to move it if you add another language. + {{% /alert %}} -For adding multiple language versions of other site elements such as button text, see the [internationalization bundles](#internationalization-bundles) section below. +For adding multiple language versions of other site elements such as button +text, see the [internationalization bundles](#internationalization-bundles) +section below. + +### Right-to-left languages + +Docsy supports top-down Right-To-Left (RTL) languages such as Persian through +[Bootstrap's RTL feature][bs-rtl], which uses [RTLCSS]. + +If your multilingual site includes an RTL language (configured with +`languageDirection: rtl`), then your project needs to include the [`rtlcss` +package]. You can add this package to your dev dependencies as follows: + +```sh +npm install rtlcss --save-dev +``` + +For an example of Docsy's RTL support, see the [Persian pages] of the [Docsy +example]. + +[bs-rtl]: https://getbootstrap.com/docs/5.3/getting-started/rtl/ +[RTLCSS]: https://rtlcss.com/ +[`rtlcss` package]: https://www.npmjs.com/package/rtlcss +[Persian pages]: https://example.docsy.dev/fa/ ## Selecting a language -If you configure more than one language in your [configuration file](https://gohugo.io/getting-started/configuration/#configuration-file), the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language. +If you configure more than one language in your +[configuration file](https://gohugo.io/getting-started/configuration/#configuration-file), +the Docsy theme adds a language selector drop down to the top-level menu. +Selecting a language takes the user to the translated version of the current +page, or the home page for the given language. ## Internationalization bundles -All UI strings (text for buttons, repository links, etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language. +All UI strings (text for buttons, repository links, etc.) are bundled inside +`/i18n` in the theme, with a `.toml` file for each language. -If your chosen language isn't currently in the theme and you create your own `.toml` file for all the common UI strings (for example, if you translate the UI text into Esperanto and create a copy of `en.toml` called `eo.toml`), we recommend you do this **in the theme** rather than in your own project. You can then open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to contribute your translation to the Docsy community. +If your chosen language isn't currently in the theme and you create your own +`.toml` file for all the common UI strings (for example, if you translate the UI +text into Esperanto and create a copy of `en.toml` called `eo.toml`), we +recommend you do this **in the theme** rather than in your own project. You can +then open a +[pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) +to contribute your translation to the Docsy community. -{{% alert title="Hugo Tip" %}} -Run `hugo server --printI18nWarnings` when doing translation work, as it will give you warnings on what strings are missing. +{{% alert title="Hugo Tip" %}} Run `hugo server --printI18nWarnings` when doing +translation work, as it will give you warnings on what strings are missing. {{% /alert %}} ### Create custom UI strings -If any of the Docsy theme UI strings in your chosen language aren't suitable for your project, or if you need additional strings for your site, you can create your own project-specific internationalization file in your project's `/i18n` directory. For example, if you want to override any of Docsy's [English-language strings](https://github.com/google/docsy/blob/main/i18n/en.toml), create your own `/i18n/en.toml` with just your custom strings. Any values you specify in this file will override the theme versions, while the remaining strings will come from the theme's corresponding internationalization bundle. +If any of the Docsy theme UI strings in your chosen language aren't suitable for +your project, or if you need additional strings for your site, you can create +your own project-specific internationalization file in your project's `/i18n` +directory. For example, if you want to override any of Docsy's +[English-language strings](https://github.com/google/docsy/blob/main/i18n/en.toml), +create your own `/i18n/en.toml` with just your custom strings. Any values you +specify in this file will override the theme versions, while the remaining +strings will come from the theme's corresponding internationalization bundle. + +[Docsy example]: https://example.docsy.dev/ diff --git a/userguide/content/en/docs/updating/_index.md b/userguide/content/en/docs/updating/_index.md index bc7c9fac1b..86639cbe87 100644 --- a/userguide/content/en/docs/updating/_index.md +++ b/userguide/content/en/docs/updating/_index.md @@ -1,19 +1,27 @@ --- -title: "Update Docsy" -linkTitle: "Update Docsy" +title: Update Docsy +description: Keeping the Docsy theme up to date. weight: 8 -description: > - Keeping the Docsy theme up to date. --- -We hope to continue to make improvements to the theme [along with the Docsy community](/docs/contribution-guidelines/). -If you have cloned the example site (or are otherwise using the theme as a Hugo Module or Git submodule), you can easily update the Docsy theme in your site yourself. If you have cloned the theme itself into your own project you can also update, though you may need to resolve merge conflicts. +We hope to continue to make improvements to the theme +[along with the Docsy community](/docs/contribution-guidelines/). If you have +cloned the example site (or are otherwise using the theme as a Hugo Module or +Git submodule), you can easily update the Docsy theme in your site yourself. If +you have cloned the theme itself into your own project you can also update, +though you may need to resolve merge conflicts. -Updating Docsy means that your site will build using the latest version of Docsy at `HEAD` and include -all the new commits or changes that have been merged since the point in time that you initially added the Docsy -submodule, or last updated. Updating won't affect any modifications that you made in your own project to -[override the Docsy look and feel](/docs/adding-content/lookandfeel/), as your overrides -don't modify the theme itself. For details about what has changed in the theme since your last update, see the list of +Updating Docsy means that your site will build using the latest version of Docsy +at `HEAD` and include all the new commits or changes that have been merged since +the point in time that you initially added the Docsy submodule, or last updated. +Updating won't affect any modifications that you made in your own project to +[override the Docsy look and feel](/docs/adding-content/lookandfeel/), as your +overrides don't modify the theme itself. For details about what has changed in +the theme since your last update, see the list of [Docsy commits](https://github.com/google/docsy/commits/main). -If you have been using the theme as a Git submodule, you can also update your site to use [Docsy as a Hugo Module](/docs/get-started/docsy-as-module/). This is the latest and simplest way to pull in a Hugo theme from its repository. If you're not ready to migrate to Hugo Modules yet, don't worry, your site will still work and you can continue to update your submodule as before. +If you have been using the theme as a Git submodule, you can also update your +site to use [Docsy as a Hugo Module](/docs/get-started/docsy-as-module/). This +is the latest and simplest way to pull in a Hugo theme from its repository. If +you're not ready to migrate to Hugo Modules yet, don't worry, your site will +still work and you can continue to update your submodule as before. diff --git a/userguide/content/en/docs/updating/convert-site-to-module.md b/userguide/content/en/docs/updating/convert-site-to-module.md index a6fb3452bf..694b680e97 100644 --- a/userguide/content/en/docs/updating/convert-site-to-module.md +++ b/userguide/content/en/docs/updating/convert-site-to-module.md @@ -78,10 +78,10 @@ In your `hugo.toml`/`hugo.yaml`/`hugo.json` file, update the theme setting to us {{< tab header="hugo.toml" lang="toml" >}} theme = ["docsy"] {{< /tab >}} -{{< tab header="config.yaml" lang="yaml" >}} +{{< tab header="hugo.yaml" lang="yaml" >}} theme: docsy {{< /tab >}} -{{< tab header="config.json" lang="json" >}} +{{< tab header="hugo.json" lang="json" >}} "theme": "docsy" {{< /tab >}} {{< /tabpane >}} @@ -93,7 +93,7 @@ Change this line to: {{< tab header="hugo.toml" lang="toml" >}} theme = ["github.com/google/docsy"] {{< /tab >}} -{{< tab header="config.yaml" lang="yaml" >}} +{{< tab header="hugo.yaml" lang="yaml" >}} theme: - github.com/google/docsy {{< /tab >}} diff --git a/userguide/content/en/project/_index.md b/userguide/content/en/project/_index.md new file mode 100644 index 0000000000..c41155d24b --- /dev/null +++ b/userguide/content/en/project/_index.md @@ -0,0 +1,24 @@ +--- +title: Docsy project +linkTitle: Project +description: Docsy project design documentation and other resources +outputs: [HTML] +cascade: + type: docs + params: + ui: + breadcrumb_disable: true + github_subdir: '' + path_base_for_github_subdir: + from: '^(.*)/(\w+\.md)' + to: $2 +params: + github_subdir: userguide # cSpell:disable-line + path_base_for_github_subdir: '' +--- + +- Docsy build and design notes (TBC) +- Repository files: + - [CHANGELOG](changelog) + - [CONTRIBUTING](contributing) + - [README](readme) diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index 2f9435dcd2..5143fdeb53 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -1,14 +1,12 @@ baseURL: https://www.docsy.dev/ -title: &title Docsy -description: &desc Docsy does docs +title: Docsy enableRobotsTXT: true -theme: [docsy] enableGitInfo: true +theme: [docsy] -pygmentsCodeFences: true -pygmentsUseClasses: false -pygmentsUseClassic: false -pygmentsStyle: tango +ignoreLogs: + # FIXME: find a better way to encode `project` pages than having to ignore warnings. + - warning-frontmatter-params-overrides # cSpell:disable-line outputs: home: [HTML] @@ -16,7 +14,7 @@ outputs: section: [HTML, RSS, print] imaging: - resampleFilter: CatmullRom + resampleFilter: CatmullRom # cSpell:disable-line quality: 75 anchor: smart @@ -32,19 +30,23 @@ languages: en: languageName: English params: - title: *title - description: *desc + description: Docsy does docs markup: goldmark: parser: attribute: block: true + extensions: + passthrough: + enable: true + delimiters: + block: [['\[', '\]'], ['$$', '$$']] + inline: [['\(', '\)']] renderer: unsafe: true highlight: - noClasses: false - style: tango + noClasses: false # Required for dark-mode params: copyright: @@ -55,7 +57,7 @@ params: privacy_policy: https://policies.google.com/privacy version_menu: Releases archived_version: false - version: 0.9.1 + version: 0.12.0 url_latest_version: https://example.com github_repo: https://github.com/google/docsy github_project_repo: https://github.com/google/docsy @@ -63,7 +65,7 @@ params: time_format_blog: Monday, January 02, 2006 time_format_default: January 2, 2006 rss_sections: [blog] # TODO: drop since this is the default - gcs_engine_id: 011217106833237091527:la2vtv2emlw + gcs_engine_id: 011217106833237091527:la2vtv2emlw # cSpell:disable-line offlineSearch: false offlineSearchSummaryLength: 70 offlineSearchMaxResults: 10 @@ -107,6 +109,10 @@ params: icon: fa-brands fa-stack-overflow desc: Practical questions and curated answers developer: + - name: Project info + url: /project/ + icon: fa fa-book + desc: Project design documentation and resources - name: GitHub url: https://github.com/google/docsy icon: fa-brands fa-github @@ -132,3 +138,12 @@ module: mounts: - source: content/en target: content + # Mount the repo's top-level .md files under project + - source: ../README.md + target: content/project/readme.md + - source: ../CHANGELOG.md + target: content/project/changelog.md + - source: ../CONTRIBUTING.md + target: content/project/contributing.md + +# cSpell:ignore docsy github goldmark markmap plantuml readingtime userguide diff --git a/userguide/layouts/_default/_markup/render-heading.html b/userguide/layouts/_markup/render-heading.html similarity index 69% rename from userguide/layouts/_default/_markup/render-heading.html rename to userguide/layouts/_markup/render-heading.html index 6cb98f1686..ac2cdb6a5d 100644 --- a/userguide/layouts/_default/_markup/render-heading.html +++ b/userguide/layouts/_markup/render-heading.html @@ -1,4 +1,4 @@ -{{ template "_default/_markup/td-render-heading.html" . -}} +{{ partial "td/render-heading.html" . -}} {{/* By default, the markdown processor emits a heading on its own line, so we don't trim whitespace from the end of this template. */}} diff --git a/userguide/package.json b/userguide/package.json index 56f0ce2d3e..f9a4b269f6 100644 --- a/userguide/package.json +++ b/userguide/package.json @@ -1,29 +1,38 @@ { "name": "docsy-user-guide", "scripts": { - "_build": "npm run _hugo-dev", - "_check:links": "make check-links", - "_hugo": "hugo --cleanDestinationDir --themesDir ../..", + "_build": "npm run _hugo-dev --", + "_check:format": "npx prettier --prose-wrap=always --check .", + "_check:links--warn": "npm run _check:links || (echo; echo 'WARNING: see link-checker output for issues.'; echo)", + "_check:links": "make --keep-going check-links", + "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit -m \"Site at $HASH\"", "_hugo-dev": "npm run _hugo -- -e dev -DFE", - "_serve": "npm run _hugo-dev -- --minify serve", - "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", + "_hugo": "hugo --cleanDestinationDir --themesDir ../..", + "_refcache:prune": "jq 'with_entries(select(.value.StatusCode < 400))' static/refcache.json > tmp/refcache.json && mv tmp/refcache.json static/refcache.json", + "_serve": "npm run _hugo-dev -- serve --minify --disableFastRender --renderToMemory", + "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-http://localhost}\"", "build:production": "npm run _hugo -- --minify", - "build": "npm run _build", - "check:links:all": "HTMLTEST_ARGS= npm run _check:links", + "build": "npm run _build --", + "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", + "check:links:internal": "HTMLTEST_ARGS='--skip-external' npm run _check:links", "check:links": "npm run _check:links", "clean": "rm -Rf public", + "fix:format": "npm run _check:format -- --write", "make:public": "git init -b main public", + "postbuild:preview": "npm run _check:links--warn", + "postbuild:production": "npm run _check:links--warn", "precheck:links:all": "npm run build", "precheck:links": "npm run build", - "postbuild:preview": "npm run _check:links", - "postbuild:production": "npm run _check:links", "prepare": "cd .. && npm install", "serve": "npm run _serve", - "test": "npm run check:links", - "update:pkg:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest" + "test": "npm run check:format && npm run check:links", + "update:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest", + "update:pkgs": "npx npm-check-updates -u" }, "devDependencies": { - "autoprefixer": "^10.4.19", - "postcss-cli": "^11.0.0" - } + "autoprefixer": "^10.4.21", + "postcss-cli": "^11.0.1", + "rtlcss": "^4.3.0" + }, + "cSpell:ignore": "- docsy htmltest pkgs postbuild precheck refcache rtlcss -" } diff --git a/userguide/static/images/sidebar-toc-with-tocbot.png b/userguide/static/images/sidebar-toc-with-tocbot.png new file mode 100644 index 0000000000..bfdf847443 Binary files /dev/null and b/userguide/static/images/sidebar-toc-with-tocbot.png differ diff --git a/userguide/static/refcache.json b/userguide/static/refcache.json new file mode 100644 index 0000000000..523d760faf --- /dev/null +++ b/userguide/static/refcache.json @@ -0,0 +1,2522 @@ +{ + "http://cthedot.de/icongen": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.133886-04:00" + }, + "http://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.553014-04:00" + }, + "https://about.gitlab.com/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:25.833683-05:00" + }, + "https://agones.dev/site/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.32544-04:00" + }, + "https://airflow.apache.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:55.210206-04:00" + }, + "https://analytics.google.com/analytics/web/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:15.322149-05:00" + }, + "https://app.netlify.com/sites/docsydocs/deploys": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:35.841165-05:00" + }, + "https://aws.amazon.com": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:42.857021-04:00" + }, + "https://aws.amazon.com/amplify/console/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:47.993892-04:00" + }, + "https://aws.amazon.com/codecommit/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:37.335697-04:00" + }, + "https://bitbucket.org/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.963599-04:00" + }, + "https://bitbucket.org/product": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:35.872023-05:00" + }, + "https://blog.cavelab.dev/2021/10/hugo-aliases-to-s3-redirects/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:47.463035-04:00" + }, + "https://blog.getbootstrap.com/2022/07/19/bootstrap-5-2-0/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.720873-05:00" + }, + "https://blog.getbootstrap.com/2023/05/30/bootstrap-5-3-0/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:45.233113-05:00" + }, + "https://blog.getbootstrap.com/2023/05/30/bootstrap-5-3-0/#custom-color-modes": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:50.321773-05:00" + }, + "https://capgemini.github.io/development/Using-GitHub-Actions-and-Hugo-Deploy-to-Deploy-to-AWS/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:46.486412-04:00" + }, + "https://cdn.jsdelivr.net/npm/markmap-autoloader": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:46.294443-05:00" + }, + "https://cla.developers.google.com/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:15.498153-05:00" + }, + "https://cloud-native.slack.com/archives/CUJ6W5TLM": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:07.527619-05:00" + }, + "https://code.jquery.com/jquery-3.7.1.min.js": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:54.327311-05:00" + }, + "https://commons.wikimedia.org/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.863191-04:00" + }, + "https://creativecommons.org/licenses/by/4.0": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:35.685279-05:00" + }, + "https://cse.google.com/cse/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:25.912167-05:00" + }, + "https://cse.google.com/cse/all": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.121607-04:00" + }, + "https://cthedot.de/icongen": { + "StatusCode": 206, + "LastSeen": "2025-05-22T22:35:07.769384352+02:00" + }, + "https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:24.495606-05:00" + }, + "https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink#values": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:58.431064-05:00" + }, + "https://developer.mozilla.org/en-US/docs/Web/CSS/position#values": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:47.423046-05:00" + }, + "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.834465-04:00" + }, + "https://developers.google.com/search/docs/beginner/seo-starter-guide": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:40.634964-04:00" + }, + "https://developers.google.com/style/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.192904-04:00" + }, + "https://developers.google.com/style/highlights": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.90393-04:00" + }, + "https://diagrams.net/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:41.460308-04:00" + }, + "https://discourse.gohugo.io/t/config-is-services-googleanalytics-id-an-alias-for-googleanalytics/39469": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:37.88603-04:00" + }, + "https://discourse.gohugo.io/t/hugo-v0-112-0-new-template-functions/44512": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:46.242317-05:00" + }, + "https://discourse.gohugo.io/t/markdown-attributes/41783": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:46.115114-04:00" + }, + "https://discourse.gohugo.io/t/what-does-setting-hugo-env-to-production-do/24669/2": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:38.235785-04:00" + }, + "https://docs.agilebase.co.uk/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.839753-04:00" + }, + "https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.098848-04:00" + }, + "https://docs.aws.amazon.com/cli/latest/userguide/get-started-install.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:44.659444-04:00" + }, + "https://docs.dapr.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:59.181072-04:00" + }, + "https://docs.docker.com/compose/install/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.689174-04:00" + }, + "https://docs.docker.com/engine/install/#server": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.902239-04:00" + }, + "https://docs.docker.com/engine/reference/builder/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.116997-04:00" + }, + "https://docs.docker.com/get-docker/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.001531-04:00" + }, + "https://docs.github.com/en/actions": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:46.253261-04:00" + }, + "https://docs.github.com/en/actions/deployment/about-deployments/about-continuous-deployment": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.222122-04:00" + }, + "https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.603738-04:00" + }, + "https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.966243-04:00" + }, + "https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.513792-04:00" + }, + "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.173207-04:00" + }, + "https://docs.gitlab.com/ee/user/markdown.html#math": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.113375-04:00" + }, + "https://docs.layer5.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:52.27212-04:00" + }, + "https://docs.netlify.com/configure-builds/file-based-configuration/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.603725-04:00" + }, + "https://docs.npmjs.com/cli/v10/commands/npm-install#description": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.893423-04:00" + }, + "https://docs.npmjs.com/cli/v10/using-npm/scripts": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.909516-04:00" + }, + "https://docs.npmjs.com/cli/v10/using-npm/scripts#prepare-and-prepublish": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:08:59.437626-05:00" + }, + "https://docsearch.algolia.com": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:35.804716-05:00" + }, + "https://docsearch.algolia.com/apply": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.103299-04:00" + }, + "https://docsearch.algolia.com/docs/DocSearch-v3": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:09:10.09504-05:00" + }, + "https://docsearch.algolia.com/docs/legacy/dropdown/#testing": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.551926-04:00" + }, + "https://docsearch.algolia.com/docs/migrating-from-v2": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:09:15.363173-05:00" + }, + "https://docsy.dev": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:31.312948-05:00" + }, + "https://docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:56.490013-05:00" + }, + "https://docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package": { + "StatusCode": 206, + "LastSeen": "2024-11-19T17:24:40.908287-05:00" + }, + "https://ds-docs.y.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:53.96896-04:00" + }, + "https://en.wikibooks.org/wiki/LaTeX/Mathematics": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.41467-04:00" + }, + "https://en.wikipedia.org/wiki/Breadcrumb_navigation": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.863129-04:00" + }, + "https://en.wikipedia.org/wiki/Don%27t_repeat_yourself": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:35.708092-04:00" + }, + "https://en.wikipedia.org/wiki/Wordmark": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:44.997719-04:00" + }, + "https://endoflife.date/bootstrap": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:46.366427-05:00" + }, + "https://etcd.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:50.317635-04:00" + }, + "https://example.docsy.dev": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:59.699509-05:00" + }, + "https://example.docsy.dev/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.493743-04:00" + }, + "https://example.docsy.dev/about/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.603703-04:00" + }, + "https://example.docsy.dev/fa/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.971966-04:00" + }, + "https://fabform.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.403783-04:00" + }, + "https://fabform.io/a/hugo-contact-form": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.754335-04:00" + }, + "https://favicon.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.474705-04:00" + }, + "https://fission.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:46.493502-04:00" + }, + "https://flaviocopes.com/npm-packages-local-global/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.306779-04:00" + }, + "https://fluxcd.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.1984-04:00" + }, + "https://fontawesome.com/docs/web/setup/upgrade/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:08:33.481615-05:00" + }, + "https://fontawesome.com/docs/web/setup/upgrade/whats-changed": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:08:38.786091-05:00" + }, + "https://fontawesome.com/icons": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:35.719842-04:00" + }, + "https://fontawesome.com/icons/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:34.55851-04:00" + }, + "https://fonts.google.com/specimen/Open+Sans": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:39.50344-04:00" + }, + "https://gchq.github.io/stroom-docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:47.572497-04:00" + }, + "https://getbootstrap.com": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:41.008371-05:00" + }, + "https://getbootstrap.com/docs/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.7457-04:00" + }, + "https://getbootstrap.com/docs/4.1/components/card/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:09:26.306871-05:00" + }, + "https://getbootstrap.com/docs/5.2/customize/sass/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:19.851166-05:00" + }, + "https://getbootstrap.com/docs/5.2/layout/breakpoints": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:01.658559-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:13.382233-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:41.045472-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#forms": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:29.453076-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#grid-updates": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:56.514751-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#javascript": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.432366-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#new-_mapsscss": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:25.038042-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#rtl": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:40.10422-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#sass": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:06.733431-05:00" + }, + "https://getbootstrap.com/docs/5.2/migration/#utilities": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:46.341081-05:00" + }, + "https://getbootstrap.com/docs/5.3/content/tables/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.464085-04:00" + }, + "https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.688361-04:00" + }, + "https://getbootstrap.com/docs/5.3/customize/color-modes/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.448386-05:00" + }, + "https://getbootstrap.com/docs/5.3/customize/color-modes/#adding-theme-colors": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.550216-04:00" + }, + "https://getbootstrap.com/docs/5.3/customize/color-modes/#dark-mode": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:56.522694-05:00" + }, + "https://getbootstrap.com/docs/5.3/customize/color/#color-sass-maps": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.002213-04:00" + }, + "https://getbootstrap.com/docs/5.3/customize/sass/#maps-and-loops": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.268214-04:00" + }, + "https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.540758-04:00" + }, + "https://getbootstrap.com/docs/5.3/getting-started/rtl/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.45515-05:00" + }, + "https://gf.dev/x-frame-options-test": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:40.429824-04:00" + }, + "https://git-scm.com/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.87032-04:00" + }, + "https://git-scm.com/book/en/v2/Git-Tools-Submodules": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.752578-04:00" + }, + "https://gitea.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.974618-04:00" + }, + "https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:38.819163-04:00" + }, + "https://github.com": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:10.082415-05:00" + }, + "https://github.com/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:20.217545-05:00" + }, + "https://github.com/GoogleContainerTools/kpt/tree/main/docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.603772-04:00" + }, + "https://github.com/KaTeX/KaTeX/tree/main/contrib/mhchem": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.133895-04:00" + }, + "https://github.com/LisaFC": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:41.54171-05:00" + }, + "https://github.com/Redocly/redoc": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.819822-04:00" + }, + "https://github.com/SeleniumHQ/seleniumhq.github.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:46.2392-04:00" + }, + "https://github.com/Xceptance/xlt-documentation": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:58.767244-04:00" + }, + "https://github.com/YCloudYUSA/yusaopeny_docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:54.827763-04:00" + }, + "https://github.com/alecthomas/chroma": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.320782-04:00" + }, + "https://github.com/apache/airflow-site/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:55.902795-04:00" + }, + "https://github.com/cchesser/java-perf-workshop": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.566383-04:00" + }, + "https://github.com/chalin": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:15.089511-05:00" + }, + "https://github.com/chalin/docsy-starter": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:36.174008-05:00" + }, + "https://github.com/chalin/docsy/blob/849dea0790bbaef5f4f71659824f44045afcd65e/assets/scss/_content.scss#L98": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:34:57.962962-04:00" + }, + "https://github.com/cloudwego/cloudwego.github.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:50.065258-04:00" + }, + "https://github.com/dapr/docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:59.789257-04:00" + }, + "https://github.com/deining": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:09:48.106528-05:00" + }, + "https://github.com/emckean": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:51.894824-05:00" + }, + "https://github.com/etcd-io/website": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:51.140059-04:00" + }, + "https://github.com/fission/fission.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:47.250123-04:00" + }, + "https://github.com/fluxcd/website": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.987649-04:00" + }, + "https://github.com/gchq/stroom-docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:48.378305-04:00" + }, + "https://github.com/geriom": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:46.520121-05:00" + }, + "https://github.com/git-guides/install-git": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.398332-04:00" + }, + "https://github.com/gohugoio/hugo/releases": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:57.31931-05:00" + }, + "https://github.com/gohugoio/hugo/releases/tag/v0.112.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:35.928948-05:00" + }, + "https://github.com/gohugoio/hugo/releases/tag/v0.120.0": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.710274-04:00" + }, + "https://github.com/gohugoio/hugo/releases/tag/v0.123.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:36.030093-05:00" + }, + "https://github.com/google/.github/blob/master/CODE_OF_CONDUCT.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:59.72164-04:00" + }, + "https://github.com/google/docsy": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:30.503171-05:00" + }, + "https://github.com/google/docsy-example": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:10.453664-05:00" + }, + "https://github.com/google/docsy-example/blob/f88fca475c28ffba3d72710a50450870230eb3a0/hugo.toml#L222-L227": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.344437-04:00" + }, + "https://github.com/google/docsy-example/blob/main/hugo.yaml": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:37:54.687836-04:00" + }, + "https://github.com/google/docsy-example/issues/285": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:22.304468-05:00" + }, + "https://github.com/google/docsy-example/pull/220": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:58.879594-05:00" + }, + "https://github.com/google/docsy-example/pull/221": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:47.429416-05:00" + }, + "https://github.com/google/docsy-example/tree/main/content/en": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.764516-04:00" + }, + "https://github.com/google/docsy-example/tree/main/content/en/blog": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.856971-04:00" + }, + "https://github.com/google/docsy/blob/main/.github/workflows": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:59.41388-04:00" + }, + "https://github.com/google/docsy/blob/main/CHANGELOG.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.644317-04:00" + }, + "https://github.com/google/docsy/blob/main/CHANGELOG.md#070": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:59.003265-04:00" + }, + "https://github.com/google/docsy/blob/main/CHANGELOG.md/#080": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.869648-04:00" + }, + "https://github.com/google/docsy/blob/main/CHANGELOG.md/#090": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.910917-04:00" + }, + "https://github.com/google/docsy/blob/main/CONTRIBUTING.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:37:00.213025-04:00" + }, + "https://github.com/google/docsy/blob/main/LICENSE": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.720392-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/js/search.js": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.241415-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/_nav.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:44.659548-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/_search.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.731243-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.469898-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/_variables.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.296204-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.729995-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/_variables_project_after_bs.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.591288-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/td/chroma/_dark.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.845847-04:00" + }, + "https://github.com/google/docsy/blob/main/assets/scss/td/chroma/_light.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.413544-04:00" + }, + "https://github.com/google/docsy/blob/main/go.mod": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:37:00.009501-04:00" + }, + "https://github.com/google/docsy/blob/main/i18n/en.toml": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.405106-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/_partials/head.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:35:01.197874-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/_partials/hooks/body-end.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:35:01.546478-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/_partials/hooks/head-end.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:46.646572-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/_partials/page-description.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.687112-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/_partials/search-input.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.127906-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/_td-content-after-header.html": { + "StatusCode": 206, + "LastSeen": "2025-05-23T09:04:28.74017-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/baseof.html": { + "StatusCode": 206, + "LastSeen": "2025-05-22T12:25:13.516369-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/blog/baseof.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.383402-04:00" + }, + "https://github.com/google/docsy/blob/main/layouts/docs/baseof.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.87696-04:00" + }, + "https://github.com/google/docsy/blob/main/netlify.toml": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.091263-04:00" + }, + "https://github.com/google/docsy/blob/main/package.json": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.931728-04:00" + }, + "https://github.com/google/docsy/blob/main/userguide/hugo.yaml": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:59.550403-04:00" + }, + "https://github.com/google/docsy/blob/v0.7.0/assets/scss/main.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:14.471568-04:00" + }, + "https://github.com/google/docsy/blob/v0.7.0/layouts/partials/footer.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:13.572344-04:00" + }, + "https://github.com/google/docsy/commit/020f8608f7ce8dcc4b17cbeb6519c1debd7d89fd": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:01.047795-05:00" + }, + "https://github.com/google/docsy/commit/624a8a5cfc5ce85b88d72b0072a6638151db6f23": { + "StatusCode": 200, + "LastSeen": "2024-11-07T05:42:56.358626-05:00" + }, + "https://github.com/google/docsy/commit/6bb4f99d1eab4976fb80d1488c81ba12b1715c05": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.607877-04:00" + }, + "https://github.com/google/docsy/commit/712aa05897c1abe239786522131e83d69e5e1b4e": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:36.233252-05:00" + }, + "https://github.com/google/docsy/commit/930781cec8c7b62ec4f334451bc2448f611974ae": { + "StatusCode": 200, + "LastSeen": "2024-11-07T05:42:56.424252-05:00" + }, + "https://github.com/google/docsy/commit/dd432d428dda757e3e6f2f4244d68c004f9edd3c": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:00.852956-05:00" + }, + "https://github.com/google/docsy/commit/f2e336222ac52aac74fc6ca9bbba24569e91849d": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:07.854607-05:00" + }, + "https://github.com/google/docsy/commits/main": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.203482-04:00" + }, + "https://github.com/google/docsy/compare/v0.8.0...v0.9.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:36.036568-05:00" + }, + "https://github.com/google/docsy/discussions": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:05.057915-05:00" + }, + "https://github.com/google/docsy/discussions/1308": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:46.589992-05:00" + }, + "https://github.com/google/docsy/discussions/1555": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:04.169461-05:00" + }, + "https://github.com/google/docsy/discussions/798": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:21.244263-05:00" + }, + "https://github.com/google/docsy/discussions/950": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:10.254503-05:00" + }, + "https://github.com/google/docsy/discussions/categories/announcement": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:09.017642-05:00" + }, + "https://github.com/google/docsy/discussions/new": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:12.720723-05:00" + }, + "https://github.com/google/docsy/graphs/contributors": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:36.375028-05:00" + }, + "https://github.com/google/docsy/issues": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:36.408184-05:00" + }, + "https://github.com/google/docsy/issues/1120": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:40.795958-05:00" + }, + "https://github.com/google/docsy/issues/1154": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:09:32.113589-05:00" + }, + "https://github.com/google/docsy/issues/1185": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:55.756687-05:00" + }, + "https://github.com/google/docsy/issues/1369": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:33.896911-05:00" + }, + "https://github.com/google/docsy/issues/138": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:30.69447-05:00" + }, + "https://github.com/google/docsy/issues/1385": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:19.286462-05:00" + }, + "https://github.com/google/docsy/issues/1436": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:12:04.025686-05:00" + }, + "https://github.com/google/docsy/issues/1442": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:35.06986-05:00" + }, + "https://github.com/google/docsy/issues/1460": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:04.424906-05:00" + }, + "https://github.com/google/docsy/issues/1466": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:19.11148-05:00" + }, + "https://github.com/google/docsy/issues/1472": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:02.89355-05:00" + }, + "https://github.com/google/docsy/issues/1510": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:29.462912-05:00" + }, + "https://github.com/google/docsy/issues/1528": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:46.866324-05:00" + }, + "https://github.com/google/docsy/issues/1560": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:11.763814-05:00" + }, + "https://github.com/google/docsy/issues/1579": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:17.600933-05:00" + }, + "https://github.com/google/docsy/issues/1641": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:54.674516-05:00" + }, + "https://github.com/google/docsy/issues/1759": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:24.736233-05:00" + }, + "https://github.com/google/docsy/issues/1787": { + "StatusCode": 206, + "LastSeen": "2025-01-07T17:47:01.735556-05:00" + }, + "https://github.com/google/docsy/issues/1788": { + "StatusCode": 206, + "LastSeen": "2025-01-08T13:26:59.139291-05:00" + }, + "https://github.com/google/docsy/issues/1812": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:52.305697-05:00" + }, + "https://github.com/google/docsy/issues/1814": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:09.452354-05:00" + }, + "https://github.com/google/docsy/issues/1820": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:23.626024-05:00" + }, + "https://github.com/google/docsy/issues/1841": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:53.214345-05:00" + }, + "https://github.com/google/docsy/issues/1845": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:40.553863-05:00" + }, + "https://github.com/google/docsy/issues/1852": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:57.626147-05:00" + }, + "https://github.com/google/docsy/issues/1944": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:30.590037-05:00" + }, + "https://github.com/google/docsy/issues/2": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:14.152281-05:00" + }, + "https://github.com/google/docsy/issues/2108": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:45.620648-05:00" + }, + "https://github.com/google/docsy/issues/2116": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.019418-04:00" + }, + "https://github.com/google/docsy/issues/331": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:57.646409-05:00" + }, + "https://github.com/google/docsy/issues/349": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:51.973091-05:00" + }, + "https://github.com/google/docsy/issues/375": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:58.056581-05:00" + }, + "https://github.com/google/docsy/issues/470": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:31.810529-05:00" + }, + "https://github.com/google/docsy/issues/726": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:14.036489-05:00" + }, + "https://github.com/google/docsy/issues/906": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:39.719545-05:00" + }, + "https://github.com/google/docsy/issues/921": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.462183-04:00" + }, + "https://github.com/google/docsy/issues/939": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:08.372543-05:00" + }, + "https://github.com/google/docsy/issues/new": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:10.099171-05:00" + }, + "https://github.com/google/docsy/milestone/2": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:30.645035-05:00" + }, + "https://github.com/google/docsy/milestones": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:41.439291-05:00" + }, + "https://github.com/google/docsy/network/dependents": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:35.903218-05:00" + }, + "https://github.com/google/docsy/pull/1009": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:09:21.188261-05:00" + }, + "https://github.com/google/docsy/pull/1367": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:08.065483-05:00" + }, + "https://github.com/google/docsy/pull/1373": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:30.48777-05:00" + }, + "https://github.com/google/docsy/pull/1388": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:35.025773-05:00" + }, + "https://github.com/google/docsy/pull/1410": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:23.874043-05:00" + }, + "https://github.com/google/docsy/pull/1462": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:56.190944-05:00" + }, + "https://github.com/google/docsy/pull/1472": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:53.215306-05:00" + }, + "https://github.com/google/docsy/pull/1500": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:02.825174-05:00" + }, + "https://github.com/google/docsy/pull/1502#issue-1678874640": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:42.233022-05:00" + }, + "https://github.com/google/docsy/pull/1523": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:36.557802-05:00" + }, + "https://github.com/google/docsy/pull/1566": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:00.570989-05:00" + }, + "https://github.com/google/docsy/pull/1651": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:31.959133-05:00" + }, + "https://github.com/google/docsy/pull/1661": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:00.58422-05:00" + }, + "https://github.com/google/docsy/pull/1662": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:38.396473-05:00" + }, + "https://github.com/google/docsy/pull/1726": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:13.267815-05:00" + }, + "https://github.com/google/docsy/pull/1727": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:07.491737-05:00" + }, + "https://github.com/google/docsy/pull/1744": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:36.696918-05:00" + }, + "https://github.com/google/docsy/pull/1815": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:15.331707-05:00" + }, + "https://github.com/google/docsy/pull/1817": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:08.358602-05:00" + }, + "https://github.com/google/docsy/pull/1818": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:47.022292-05:00" + }, + "https://github.com/google/docsy/pull/1896": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:19.078138-05:00" + }, + "https://github.com/google/docsy/pull/1908": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:02.418764-05:00" + }, + "https://github.com/google/docsy/pull/1915": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:08.07516-05:00" + }, + "https://github.com/google/docsy/pull/1920": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:13.892827-05:00" + }, + "https://github.com/google/docsy/pull/1922": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:02.883712-05:00" + }, + "https://github.com/google/docsy/pull/1933": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:33.799485-05:00" + }, + "https://github.com/google/docsy/pull/1952": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:13.893357-05:00" + }, + "https://github.com/google/docsy/pull/2160": { + "StatusCode": 206, + "LastSeen": "2025-01-08T13:26:59.610341-05:00" + }, + "https://github.com/google/docsy/pull/2192": { + "StatusCode": 206, + "LastSeen": "2025-02-10T11:24:51.123801-05:00" + }, + "https://github.com/google/docsy/pull/2223": { + "StatusCode": 206, + "LastSeen": "2025-04-24T08:05:34.239565-04:00" + }, + "https://github.com/google/docsy/pull/2243": { + "StatusCode": 206, + "LastSeen": "2025-05-16T06:49:30.016774-04:00" + }, + "https://github.com/google/docsy/pull/2257": { + "StatusCode": 206, + "LastSeen": "2025-05-22T19:21:13.299835-04:00" + }, + "https://github.com/google/docsy/pull/2259": { + "StatusCode": 206, + "LastSeen": "2025-05-22T19:21:14.104646-04:00" + }, + "https://github.com/google/docsy/pulls": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:15.642661-05:00" + }, + "https://github.com/google/docsy/releases": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:15.943218-05:00" + }, + "https://github.com/google/docsy/releases/latest": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:35.978077-05:00" + }, + "https://github.com/google/docsy/releases/new": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:02.000577-05:00" + }, + "https://github.com/google/docsy/releases/tag/v0.10.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:25.779056-05:00" + }, + "https://github.com/google/docsy/releases/tag/v0.11.0": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:16.686656-05:00" + }, + "https://github.com/google/docsy/releases/tag/v0.7.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:25.685322-05:00" + }, + "https://github.com/google/docsy/releases/tag/v0.9.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:25.774984-05:00" + }, + "https://github.com/google/docsy/releases/v0.10.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:07.856243-05:00" + }, + "https://github.com/google/docsy/releases/v0.11.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:46.627252-05:00" + }, + "https://github.com/google/docsy/releases/v0.12.0": { + "StatusCode": 206, + "LastSeen": "2025-05-27T12:33:39.089373-04:00" + }, + "https://github.com/google/docsy/releases/v0.2.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:09:37.689429-05:00" + }, + "https://github.com/google/docsy/releases/v0.3.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:09:04.862387-05:00" + }, + "https://github.com/google/docsy/releases/v0.4.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:08:12.129351-05:00" + }, + "https://github.com/google/docsy/releases/v0.5.1": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:08:06.753992-05:00" + }, + "https://github.com/google/docsy/releases/v0.6.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:08:01.153905-05:00" + }, + "https://github.com/google/docsy/releases/v0.7.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:23.097737-05:00" + }, + "https://github.com/google/docsy/releases/v0.7.1": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:07:05.97486-05:00" + }, + "https://github.com/google/docsy/releases/v0.7.2": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:24.708084-05:00" + }, + "https://github.com/google/docsy/releases/v0.8.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:34.672005-05:00" + }, + "https://github.com/google/docsy/releases/v0.9.0": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:24.353935-05:00" + }, + "https://github.com/google/docsy/releases/v0.9.1": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:18.773921-05:00" + }, + "https://github.com/google/docsy/tags": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:25.676987-05:00" + }, + "https://github.com/google/docsy/tree/main/CHANGELOG.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:01:09.767248-04:00" + }, + "https://github.com/google/docsy/tree/main/CONTRIBUTING.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:01:09.653606-04:00" + }, + "https://github.com/google/docsy/tree/main/README.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:01:09.766032-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.408049-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.315933-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts/_partials/td/render-heading.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.507485-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts/blog": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.437788-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts/community": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.904012-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts/docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.922907-04:00" + }, + "https://github.com/google/docsy/tree/main/layouts/swagger": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.674866-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.357352-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2022/hello.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.411362-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2023/bootstrap-5-migration.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.542885-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2023/docsy-0.7.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.665262-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2023/priorities-for-2024.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.511948-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2024/0.10.0.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.411434-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2024/0.9.0.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.481618-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/2024/year-in-review.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.481602-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/blog/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.492493-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.512066-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.243119-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/content.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.242968-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/diagrams-and-formulae/index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.29628-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/feedback.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.57167-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/iconsimages.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.529995-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/lookandfeel.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.571721-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/navigation.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.493918-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/print.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.357925-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/repository-links.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.589332-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/search.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.551745-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/shortcodes/index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.21104-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/taxonomy.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.497884-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/adding-content/versioning.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.243124-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/best-practices/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.484899-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/best-practices/organizing-content.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.551345-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/best-practices/site-guidance.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.509949-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/contribution-guidelines/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.247491-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/deployment/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.296555-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/examples/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.243122-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.53006-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/basic-configuration.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.510016-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/docsy-as-module/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.64377-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/docsy-as-module/example-site-as-template.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.209838-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.185609-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.497945-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/known_issues.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.366193-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/other-options.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.274673-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/get-started/quickstart-docker.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.649343-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/language/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.509831-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/updating/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.078278-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/updating/convert-site-to-module.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:33.530062-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/updating/updating-hugo-module.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.257566-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/docs/updating/updating-submodules.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.28026-04:00" + }, + "https://github.com/google/docsy/tree/main/userguide/content/en/project/_index.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:58.469879-04:00" + }, + "https://github.com/googleforgames/agones/tree/main/site": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.840129-04:00" + }, + "https://github.com/grpc/grpc.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.857129-04:00" + }, + "https://github.com/grpc/grpc.io/issues/1389": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:33.529009-05:00" + }, + "https://github.com/gwatts/mostlydocs/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.917573-04:00" + }, + "https://github.com/in-toto/in-toto.io/issues/76": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:58.403402-05:00" + }, + "https://github.com/jaegertracing/documentation/issues/746": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:39.929875-05:00" + }, + "https://github.com/jakejarvis/hugo-extended": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:42.875509-05:00" + }, + "https://github.com/jgraph/docker-drawio/blob/master/README.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.103301-04:00" + }, + "https://github.com/jmooring": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:47.078828-05:00" + }, + "https://github.com/kentcdodds/cross-env/issues/257": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:52.203675-05:00" + }, + "https://github.com/kubeflow/website": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.852406-04:00" + }, + "https://github.com/kubernetes/website": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:03.957185-05:00" + }, + "https://github.com/kubernetes/website/issues/22726": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:07.826381-05:00" + }, + "https://github.com/kubernetes/website/issues/22727": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:13.428577-05:00" + }, + "https://github.com/kubernetes/website/issues/22730": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:01.942457-05:00" + }, + "https://github.com/kubernetes/website/issues/41171": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:09.835149-05:00" + }, + "https://github.com/kubernetes/website/issues/44002": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:15.519151-05:00" + }, + "https://github.com/kubernetes/website/issues/48807": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:28.066952-05:00" + }, + "https://github.com/kubernetes/website/pull/48721": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:11:22.283287-05:00" + }, + "https://github.com/layer5io/docs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:53.055274-04:00" + }, + "https://github.com/marketplace/actions/hugo-setup": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.413416-04:00" + }, + "https://github.com/navidrome/website": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.5252-04:00" + }, + "https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.80256-04:00" + }, + "https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions-1": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.037899-04:00" + }, + "https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.655392-04:00" + }, + "https://github.com/okohll/abdocs": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.552974-04:00" + }, + "https://github.com/open-telemetry/opentelemetry.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:49.158734-04:00" + }, + "https://github.com/open-telemetry/opentelemetry.io/issues": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:24.377784-05:00" + }, + "https://github.com/open-telemetry/opentelemetry.io/issues/2419": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:18.883576-05:00" + }, + "https://github.com/open-telemetry/opentelemetry.io/issues/4023": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:28.180582-05:00" + }, + "https://github.com/open-telemetry/opentelemetry.io/issues/4990": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:24.301934-05:00" + }, + "https://github.com/open-telemetry/opentelemetry.io/pull/2490": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:36.326722-05:00" + }, + "https://github.com/orgs/twbs/discussions/37951": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:14.742157-05:00" + }, + "https://github.com/peaceiris/actions-hugo": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.959335-04:00" + }, + "https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:59.268175-04:00" + }, + "https://github.com/protocolbuffers/protocolbuffers.github.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:52.051247-04:00" + }, + "https://github.com/russross/blackfriday": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.024508-04:00" + }, + "https://github.com/sarahmaddox": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:18.644822-05:00" + }, + "https://github.com/tektoncd": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.806086-04:00" + }, + "https://github.com/theupdateframework/theupdateframework.io/pull/105": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:47.645841-05:00" + }, + "https://github.com/twbs/bootstrap/blob/v5.2.3/scss/_functions.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:14.983388-04:00" + }, + "https://github.com/twbs/bootstrap/blob/v5.2.3/scss/bootstrap.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T08:36:14.0234-04:00" + }, + "https://github.com/twbs/bootstrap/blob/v5.3.3/scss/_variables.scss": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.067995-04:00" + }, + "https://github.com/twbs/bootstrap/issues/25254": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:09.357401-05:00" + }, + "https://github.com/twbs/bootstrap/pull/28517/files#diff-41667d8b9901aa9fa52483b538bb9026c287f2c663d2fdc01acffa06888cc087L13": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:53.214753-05:00" + }, + "https://github.com/twbs/bootstrap/pull/28517/files#diff-41667d8b9901aa9fa52483b538bb9026c287f2c663d2fdc01acffa06888cc087R18": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:05:03.46348-05:00" + }, + "https://github.com/twbs/bootstrap/releases/tag/v4.6.2": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:08:22.731296-05:00" + }, + "https://github.com/vsoch": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:57.13928-05:00" + }, + "https://github.com/vsoch/docsy-jekyll": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:02.426537-05:00" + }, + "https://github.com/yuin/goldmark/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.546258-04:00" + }, + "https://gitlab.com": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.12292-04:00" + }, + "https://gitlab.com/graphviz/graphviz.gitlab.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:44.686957-04:00" + }, + "https://gitprotect.io/blog/how-to-use-github-repository-templates/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:04:41.805344-05:00" + }, + "https://go.dev/dl/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:37.200049-04:00" + }, + "https://gohugo.io": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:56.481854-05:00" + }, + "https://gohugo.io/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:04.821967-05:00" + }, + "https://gohugo.io/commands/hugo_deploy": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.566554-04:00" + }, + "https://gohugo.io/commands/hugo_gen_chromastyles/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.969968-04:00" + }, + "https://gohugo.io/commands/hugo_server/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.86023-04:00" + }, + "https://gohugo.io/configuration/params/#multilingual-sites": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.410803-04:00" + }, + "https://gohugo.io/content-management/formats/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.871891-04:00" + }, + "https://gohugo.io/content-management/formats/#additional-formats-through-external-helpers": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.181673-04:00" + }, + "https://gohugo.io/content-management/front-matter/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.15452-04:00" + }, + "https://gohugo.io/content-management/front-matter/#front-matter-cascade": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:48.130493-04:00" + }, + "https://gohugo.io/content-management/front-matter/#target-specific-pages": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.170899-04:00" + }, + "https://gohugo.io/content-management/image-processing/#image-processing-methods": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.103303-04:00" + }, + "https://gohugo.io/content-management/image-processing/#image-processing-options": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.355134-04:00" + }, + "https://gohugo.io/content-management/mathematics/#step-1": { + "StatusCode": 206, + "LastSeen": "2025-05-27T15:10:25.4380974+02:00" + }, + "https://gohugo.io/content-management/menus/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.887263-04:00" + }, + "https://gohugo.io/content-management/menus/#add-non-content-entries-to-a-menu": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.305599-04:00" + }, + "https://gohugo.io/content-management/multilingual": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.001559-04:00" + }, + "https://gohugo.io/content-management/page-bundles/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.568523-04:00" + }, + "https://gohugo.io/content-management/shortcodes/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.567684-04:00" + }, + "https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:07:44.838556-05:00" + }, + "https://gohugo.io/content-management/shortcodes/#use-shortcodes": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.941503-04:00" + }, + "https://gohugo.io/content-management/summaries/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.85365-04:00" + }, + "https://gohugo.io/content-management/syntax-highlighting/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.565587-04:00" + }, + "https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.094381-04:00" + }, + "https://gohugo.io/content-management/taxonomies/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.441322-04:00" + }, + "https://gohugo.io/content-management/taxonomies/#default-destinations": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.164179-04:00" + }, + "https://gohugo.io/content-management/taxonomies/#example-taxonomy-movie-website": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.769801-04:00" + }, + "https://gohugo.io/content-management/types/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.896939-04:00" + }, + "https://gohugo.io/content-management/urls/#aliases": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:46.986722-04:00" + }, + "https://gohugo.io/documentation/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:46.523198-05:00" + }, + "https://gohugo.io/functions/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:41.056129-05:00" + }, + "https://gohugo.io/functions/highlight/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.925135-04:00" + }, + "https://gohugo.io/functions/relref/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.578334-04:00" + }, + "https://gohugo.io/getting-started/configuration/#configuration-file": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.709142-04:00" + }, + "https://gohugo.io/getting-started/directory-structure/#directory-structure-explained": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.71916-04:00" + }, + "https://gohugo.io/getting-started/directory-structure/#static": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:56:02.293065-04:00" + }, + "https://gohugo.io/getting-started/directory-structure/#union-file-system": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:41.026546-05:00" + }, + "https://gohugo.io/getting-started/installing/#debian-and-ubuntu": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.490473-04:00" + }, + "https://gohugo.io/getting-started/installing/#homebrew-macos": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.269533-04:00" + }, + "https://gohugo.io/getting-started/installing/#linux": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.974396-04:00" + }, + "https://gohugo.io/hosting-and-deployment/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.993204-04:00" + }, + "https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:48.334405-04:00" + }, + "https://gohugo.io/hosting-and-deployment/hosting-on-github/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.24214-04:00" + }, + "https://gohugo.io/hosting-and-deployment/hosting-on-netlify/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.205292-04:00" + }, + "https://gohugo.io/hugo-modules/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:09:42.83213-05:00" + }, + "https://gohugo.io/hugo-modules/configuration/#module-config-top-level": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.436328-04:00" + }, + "https://gohugo.io/hugo-modules/theme-components/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.252946-04:00" + }, + "https://gohugo.io/methods/page/outputformats/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T10:00:22.662179-04:00" + }, + "https://gohugo.io/methods/site/copyright/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:23.921846-05:00" + }, + "https://gohugo.io/quick-reference/glossary/#content-type": { + "StatusCode": 206, + "LastSeen": "2025-02-10T11:24:50.719553-05:00" + }, + "https://gohugo.io/shortcodes/relref/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:49:15.698975-04:00" + }, + "https://gohugo.io/templates/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.548164-04:00" + }, + "https://gohugo.io/templates/base/": { + "StatusCode": 206, + "LastSeen": "2025-05-22T11:57:59.6157-04:00" + }, + "https://gohugo.io/templates/embedded/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T10:33:25.556387-04:00" + }, + "https://gohugo.io/templates/embedded/#configure-google-analytics": { + "StatusCode": 206, + "LastSeen": "2025-05-16T10:33:25.984266-04:00" + }, + "https://gohugo.io/templates/embedded/#google-analytics": { + "StatusCode": 206, + "LastSeen": "2025-05-16T10:33:25.360519-04:00" + }, + "https://gohugo.io/templates/internal/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.993115-04:00" + }, + "https://gohugo.io/templates/internal/#configure-google-analytics": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.192871-04:00" + }, + "https://gohugo.io/templates/internal/#google-analytics": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.523504-04:00" + }, + "https://gohugo.io/templates/new-templatesystem-overview/": { + "StatusCode": 206, + "LastSeen": "2025-05-22T19:21:12.30791-04:00" + }, + "https://gohugo.io/templates/render-hooks/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:58.341425-05:00" + }, + "https://gohugo.io/templates/sitemap-template/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.688072-04:00" + }, + "https://gohugo.io/themes/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.713469-04:00" + }, + "https://gohugo.io/variables/site/#the-siteparams-variable": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.107218-04:00" + }, + "https://graphviz.org": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:44.343705-04:00" + }, + "https://groups.google.com/forum/#!forum/docsy-users": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:15.318082-05:00" + }, + "https://help.github.com/articles/about-pull-requests/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:30.862657-05:00" + }, + "https://in-toto.io": { + "StatusCode": 206, + "LastSeen": "2024-12-12T10:10:52.769146-05:00" + }, + "https://jvmperf.net/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.792217-04:00" + }, + "https://katex.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.699835-04:00" + }, + "https://katex.org/docs/autorender.html#api": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.709844-04:00" + }, + "https://katex.org/docs/options.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.992092-04:00" + }, + "https://kubernetes.io": { + "StatusCode": 206, + "LastSeen": "2024-12-12T10:09:55.829225-05:00" + }, + "https://lunrjs.com/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:41.288729-05:00" + }, + "https://markmap.js.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.964944-04:00" + }, + "https://mentorship.lfx.linuxfoundation.org/project/34314eb1-0fc3-4802-ab04-2265418c2e48": { + "StatusCode": 200, + "LastSeen": "2024-12-12T12:56:59.092044-05:00" + }, + "https://mentorship.lfx.linuxfoundation.org/project/e35f28f9-f333-47a8-a76a-119567cf10ca": { + "StatusCode": 200, + "LastSeen": "2024-12-12T12:56:53.763004-05:00" + }, + "https://mermaid-js.github.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.938627-04:00" + }, + "https://mermaid-js.github.io/mermaid/#/Setup": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.364187-04:00" + }, + "https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables": { + "StatusCode": 206, + "LastSeen": "2025-05-22T22:35:07.842326703+02:00" + }, + "https://mhchem.github.io/MathJax-mhchem/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.393794-04:00" + }, + "https://mhchem.github.io/MathJax-mhchem/#pu": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.702247-04:00" + }, + "https://mostlydocs.netlify.app/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:56.641143-04:00" + }, + "https://netlify.com": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:17.787685-05:00" + }, + "https://nodejs.org/en/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:38.393726-04:00" + }, + "https://nodejs.org/en/about/releases/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:38.13366-04:00" + }, + "https://nodejs.org/en/download/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.486026-04:00" + }, + "https://opensource.google.com/conduct/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:46.449139-05:00" + }, + "https://opentelemetry.io": { + "StatusCode": 206, + "LastSeen": "2024-12-12T10:10:18.699204-05:00" + }, + "https://opentelemetry.io/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:13.618841-05:00" + }, + "https://opentelemetry.io/ecosystem/registry/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:34.919219-05:00" + }, + "https://pages.github.com/themes/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.614022-05:00" + }, + "https://parquet.apache.org": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:53.679753-04:00" + }, + "https://parquet.apache.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:53.439894-04:00" + }, + "https://plantuml.com/en/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:40.145791-04:00" + }, + "https://plantuml.com/en/guide": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:40.708022-04:00" + }, + "https://policies.google.com/privacy": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:41.207655-05:00" + }, + "https://portal.aws.amazon.com/billing/signup#/start": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:43.53975-04:00" + }, + "https://postcss.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:38.170931-04:00" + }, + "https://prettier.io": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.088752-04:00" + }, + "https://prismjs.com/download.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:44.15864-04:00" + }, + "https://prismjs.com/download.html#themes=prism\u0026languages=markup+css+clike+javascript+bash+c+csharp+cpp+go+java+markdown+python+scss+sql+toml+yaml\u0026plugins=toolbar+copy-to-clipboard": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.950837-04:00" + }, + "https://prismjs.com/index.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.098348-04:00" + }, + "https://prismjs.com/index.html#plugins": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.623717-04:00" + }, + "https://prismjs.com/index.html#supported-languages": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.346664-04:00" + }, + "https://protobuf.dev": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:51.385688-04:00" + }, + "https://rtlcss.com/": { + "StatusCode": 206, + "LastSeen": "2024-12-12T10:09:38.949346-05:00" + }, + "https://sass-lang.com/documentation/at-rules/import": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:30.528583-05:00" + }, + "https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.701748-04:00" + }, + "https://stackoverflow.com/questions/tagged/docsy": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:20.631446-05:00" + }, + "https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.2744-04:00" + }, + "https://support.google.com/analytics/answer/10220869": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:08:43.993236-05:00" + }, + "https://support.google.com/analytics/answer/1042508": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:35.721373-04:00" + }, + "https://support.google.com/analytics/answer/9322688": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:39.13356-04:00" + }, + "https://support.google.com/webmasters/answer/183668": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.800528-04:00" + }, + "https://swagger.io/tools/swagger-ui/": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:38.166173-04:00" + }, + "https://tekton.dev/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.215495-04:00" + }, + "https://themes.gohugo.io/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:56.806827-05:00" + }, + "https://theupdateframework.io": { + "StatusCode": 206, + "LastSeen": "2024-12-12T10:10:41.327928-05:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0d/Thomas_Jefferson_Signature.svg/320px-Thomas_Jefferson_Signature.svg.png": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.579153-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/2/20/James_Madison%28cropped%29%28c%29.jpg/393px-James_Madison%28cropped%29%28c%29.jpg": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.845914-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/2/2e/George_Washington_signature.svg/320px-George_Washington_signature.svg.png": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.430038-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/3/39/James_Madison_sig.svg/320px-James_Madison_sig.svg.png": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.26987-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/5/51/Firma_de_John_Lennon.svg/320px-Firma_de_John_Lennon.svg.png": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:43.596071-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/b/b1/Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg/390px-Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.287656-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/b/b6/Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg/633px-Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.198711-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/John_Adams_Sig_2.svg/320px-John_Adams_Sig_2.svg.png": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:42.014481-04:00" + }, + "https://upload.wikimedia.org/wikipedia/commons/thumb/f/ff/Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg/633px-Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.69366-04:00" + }, + "https://v0-6.kubeflow.org/docs/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.265029-04:00" + }, + "https://www.cloudpods.org": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.050336-04:00" + }, + "https://www.cloudwego.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:49.385848-04:00" + }, + "https://www.cncf.io": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:50.597735-05:00" + }, + "https://www.cncf.io/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:20.447352-05:00" + }, + "https://www.cncf.io/blog/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:18.917189-05:00" + }, + "https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:27.027319-05:00" + }, + "https://www.cncf.io/blog/2023/06/05/migrating-docsy-to-bootstrap-5/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:24.681803-05:00" + }, + "https://www.cncf.io/blog/2024/07/11/as-we-reach-mid-year-2024-a-look-at-cncf-linux-foundation-and-top-30-open-source-project-velocity/": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:09:45.500547-05:00" + }, + "https://www.cncf.io/blog/2024/09/27/congratulations-to-45-cncf-term-1-2024-lfx-program-mentees/": { + "StatusCode": 200, + "LastSeen": "2024-12-12T10:10:30.4954-05:00" + }, + "https://www.cncf.io/projects/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:06:02.20758-05:00" + }, + "https://www.ctan.org/pkg/mhchem": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:37.691511-04:00" + }, + "https://www.docker.com/get-started": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:35.492337-04:00" + }, + "https://www.docsy.dev/about/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.23027-04:00" + }, + "https://www.docsy.dev/blog/2022/hello/#introducing-the-psc": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:41.378061-05:00" + }, + "https://www.docsy.dev/blog/2023/bootstrap-5-migration/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:46.602346-05:00" + }, + "https://www.docsy.dev/blog/2024/0.10.0/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:07.422163-05:00" + }, + "https://www.docsy.dev/blog/2024/0.10.0/#color-themes-and-dark-mode-support": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:12.440347-05:00" + }, + "https://www.docsy.dev/blog/2024/0.9.0/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:23.85859-05:00" + }, + "https://www.docsy.dev/blog/2024/0.9.0/#footer-copyright": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:07.070588-05:00" + }, + "https://www.docsy.dev/blog/2024/0.9.0/#footer-layout": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:01.924772-05:00" + }, + "https://www.docsy.dev/blog/2024/0.9.0/#footer-streamlined": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:12.169389-05:00" + }, + "https://www.docsy.dev/blog/2024/0.9.0/#heading-self-links": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:56.758279-05:00" + }, + "https://www.docsy.dev/blog/2024/0.9.0/#look-and-feel": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:28.966929-05:00" + }, + "https://www.docsy.dev/blog/_print/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:54.676018-05:00" + }, + "https://www.docsy.dev/blog/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.308447-05:00" + }, + "https://www.docsy.dev/categories/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:15.698718-05:00" + }, + "https://www.docsy.dev/categories/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.341526-05:00" + }, + "https://www.docsy.dev/categories/taxonomies/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:04.815277-05:00" + }, + "https://www.docsy.dev/categories/taxonomies/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.341321-05:00" + }, + "https://www.docsy.dev/community/_print/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:54.581987-05:00" + }, + "https://www.docsy.dev/community/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.296446-05:00" + }, + "https://www.docsy.dev/docs/_print/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:54.711637-05:00" + }, + "https://www.docsy.dev/docs/adding-content/content/#adding-a-community-page": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:56.90603-05:00" + }, + "https://www.docsy.dev/docs/adding-content/content/#docs-section-landing-pages": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:36.296116-04:00" + }, + "https://www.docsy.dev/docs/adding-content/diagrams-and-formulae/#diagrams-with-mermaid": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:17.480874-05:00" + }, + "https://www.docsy.dev/docs/adding-content/feedback/#search-engine-optimization-meta-tags": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:39.579237-04:00" + }, + "https://www.docsy.dev/docs/adding-content/feedback/#setup": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:08:49.162787-05:00" + }, + "https://www.docsy.dev/docs/adding-content/feedback/#user-feedback": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:06:01.765051-05:00" + }, + "https://www.docsy.dev/docs/adding-content/lookandfeel/#before-page-content": { + "StatusCode": 206, + "LastSeen": "2025-05-22T13:24:36.066951-04:00" + }, + "https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-chroma": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:07:28.264639-05:00" + }, + "https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:29.222899-05:00" + }, + "https://www.docsy.dev/docs/adding-content/lookandfeel/#styling-your-project-logo-and-name": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:08:17.225307-05:00" + }, + "https://www.docsy.dev/docs/adding-content/navigation/#breadcrumb-navigation": { + "StatusCode": 206, + "LastSeen": "2025-01-08T13:26:58.452656-05:00" + }, + "https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links": { + "StatusCode": 206, + "LastSeen": "2025-04-23T19:48:15.989167-04:00" + }, + "https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:02.230446-05:00" + }, + "https://www.docsy.dev/docs/adding-content/repository-links/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:29.013652-05:00" + }, + "https://www.docsy.dev/docs/adding-content/repository-links/#disabling-links": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:51.427025-05:00" + }, + "https://www.docsy.dev/docs/adding-content/repository-links/#path_base_for_github_subdir-optional": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:46.126424-05:00" + }, + "https://www.docsy.dev/docs/adding-content/search/#algolia-docsearch": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:06:43.680938-05:00" + }, + "https://www.docsy.dev/docs/adding-content/shortcodes/#blocksfeature": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:17.284993-05:00" + }, + "https://www.docsy.dev/docs/adding-content/shortcodes/#blockssection": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:07:49.936454-05:00" + }, + "https://www.docsy.dev/docs/adding-content/shortcodes/#tabbed-panes": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:06:48.949389-05:00" + }, + "https://www.docsy.dev/docs/contribution-guidelines/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.724747-05:00" + }, + "https://www.docsy.dev/docs/examples/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:12.550803-05:00" + }, + "https://www.docsy.dev/docs/get-started/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:07.318282-05:00" + }, + "https://www.docsy.dev/docs/get-started/#installation-options": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:02.193448-05:00" + }, + "https://www.docsy.dev/docs/get-started/docsy-as-module/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:46.051135-05:00" + }, + "https://www.docsy.dev/docs/get-started/docsy-as-module/example-site-as-template/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.992776-04:00" + }, + "https://www.docsy.dev/docs/get-started/other-options/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:08:54.302428-05:00" + }, + "https://www.docsy.dev/docs/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.347914-05:00" + }, + "https://www.docsy.dev/docs/language/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:04:34.26295-05:00" + }, + "https://www.docsy.dev/docs/language/#internationalization-bundles": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:05:22.434922-05:00" + }, + "https://www.docsy.dev/docs/language/#right-to-left-languages": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:51.619196-05:00" + }, + "https://www.docsy.dev/docs/updating/convert-site-to-module/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:09:53.370729-05:00" + }, + "https://www.docsy.dev/tags/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:15.215542-05:00" + }, + "https://www.docsy.dev/tags/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.329546-05:00" + }, + "https://www.docsy.dev/tags/labelling/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:59.911663-05:00" + }, + "https://www.docsy.dev/tags/labelling/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.365073-05:00" + }, + "https://www.docsy.dev/tags/structuring-content/": { + "StatusCode": 200, + "LastSeen": "2024-11-06T12:03:10.066953-05:00" + }, + "https://www.docsy.dev/tags/structuring-content/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.303058-05:00" + }, + "https://www.docsy.dev/tags/tagging/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:09.961129-05:00" + }, + "https://www.docsy.dev/tags/tagging/index.xml": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:02:49.341504-05:00" + }, + "https://www.google.com/search": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:35.528804-04:00" + }, + "https://www.grpc.io/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.13321-04:00" + }, + "https://www.kubeflow.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:34.841061-04:00" + }, + "https://www.latex-project.org/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.214741-04:00" + }, + "https://www.navidrome.org": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:37.890382-04:00" + }, + "https://www.netlify.com/": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:41.203421-05:00" + }, + "https://www.netlify.com/docs/continuous-deployment/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:35.791915-04:00" + }, + "https://www.netlify.com/img/global/badges/netlify-color-accent.svg": { + "StatusCode": 206, + "LastSeen": "2024-11-06T12:03:10.241411-05:00" + }, + "https://www.noorix.com.au/blog/how-to/hosting-static-website-with-aws-s3-cloudfront/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:44.106261-04:00" + }, + "https://www.npmjs.com/package/hugo-bin": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:37.608288-04:00" + }, + "https://www.npmjs.com/package/hugo-extended": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:37.775891-04:00" + }, + "https://www.npmjs.com/package/rtlcss": { + "StatusCode": 200, + "LastSeen": "2025-05-16T09:20:36.538411-04:00" + }, + "https://www.selenium.dev/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:45.694299-04:00" + }, + "https://xltdoc.xceptance.com/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:58.025223-04:00" + }, + "https://xyproto.github.io/splash/docs/": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.351455-04:00" + }, + "https://xyproto.github.io/splash/docs/monokai.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:40.853687-04:00" + }, + "https://xyproto.github.io/splash/docs/onedark.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.551998-04:00" + }, + "https://xyproto.github.io/splash/docs/tango.html": { + "StatusCode": 206, + "LastSeen": "2025-05-16T09:20:41.078825-04:00" + } +}