diff --git a/CHANGELOG.md b/CHANGELOG.md
index f850cb53e8..babb0b1d2a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,24 +14,35 @@ For a list of issues targeted for the next release, see the [23Q1][] milestone.
**Breaking changes**:
-- **[Upgraded Bootstrap ([#470][])** to v5. For a list of Bootstrap breaking
- changes, see the [Bootstrap migration guide][bsv5mig]. Other, Docsy-specific
+- **Upgraded Bootstrap ([#470])** to v5.2. For a list of Bootstrap's breaking
+ changes, see the [Bootstrap migration guide][bsv5mig]. Other Docsy-specific
changes are listed below:
- - Clean up of unused, or rarely used, variables and functions:
- - Dropped `$primary-light`.
- - Dropped `color-diff()`.
- - BSv4 RTL support, being incompatible with BSv5, has been removed. For
- progress in RTL support, see [#1442][].
- - Dropped the `bg-gradient-variant()` mixin. [#1369][].
+ - Clean up of unused, or rarely used, variables, functions, and mixins:
+ - Dropped `$primary-light`
+ - Dropped `color-diff()`
+ - Dropped `bg-gradient-variant()` mixin ([#1369])
+ - Docsy's RTL support has been removed because it is incompatible with BSv5.
+ For progress on the reintroduction of RTL support, see [#1442].
+- **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])
+ - `blocks/section`: **default** and accepted values of the `type` argument
+ have changed! For details see [blocks/section] ([#1472]).
**Other changes**:
- Non-breaking changes that result from the Bootstrap v5 upgrade:
- - Draw.io diagram edit button: replace custom colors by BS's outline primary.
+ - Draw.io diagram edit button: replaced custom colors by BS's outline primary.
[#470]: https://github.com/google/docsy/issues/470
+[#906]: https://github.com/google/docsy/issues/906
+[#939]: https://github.com/google/docsy/issues/939
[#1369]: https://github.com/google/docsy/issues/1369
[#1442]: https://github.com/google/docsy/issues/1442
+[#1472]: https://github.com/google/docsy/issues/1472
+[blocks/section]:
+ https://www.docsy.dev/docs/adding-content/shortcodes/#blockssection
[bsv5mig]: https://getbootstrap.com/docs/5.2/migration/
## [0.6.0][]
@@ -45,9 +56,9 @@ Bootstrap version. See [the announcement][bs-announcement] for more information.
**New**:
- **Simplified use of mermaid diagrams**: when using a `mermaid` code block on
- your page, mermaid is now automatically enabled (needs hugo version >= 0.93.0).
- For existing sites build with hugo 0.93.0+, parameter `mermaid.enable`
- can be removed from site config.
+ your page, mermaid is now automatically enabled (needs hugo version >=
+ 0.93.0). For existing sites build with hugo 0.93.0+, parameter
+ `mermaid.enable` can be removed from site config.
- **Add render hook for chem code blocks**: add auto-activation of `math` and
`chem` blocks via KateX and mhchem. Support for formula rendering activation
@@ -69,11 +80,12 @@ notes][0.5.1]. **BREAKING CHANGES** are documented below.
**Breaking changes**:
-- **Tabbed panes, text display**. By default, the content of a tab inside a tabbed
- pane is shown as code. As of version 0.4 of the shortcode, you can add the
- parameter `code=false` to your `tabpane` or `tab` shortcode in order to render
- tab content(s) as text (markdown or html). As of version 0.5 the name of this
- parameter was changed, we now use `text=true` in order to mark content as text.
+- **Tabbed panes, text display**. By default, the content of a tab inside a
+ tabbed pane is shown as code. As of version 0.4 of the shortcode, you can add
+ the parameter `code=false` to your `tabpane` or `tab` shortcode in order to
+ render tab content(s) as text (markdown or html). As of version 0.5 the name
+ of this parameter was changed, we now use `text=true` in order to mark content
+ as text.
- **Display logo by default**. Most projects show their logo in the navbar. In
support of this majority, Docsy now displays a logo by default. For details on
how to hide the logo (or your brand name), see [Styling your project logo and
@@ -93,7 +105,8 @@ notes][0.5.1]. **BREAKING CHANGES** are documented below.
- By default, Docsy now uses the [gtag.js][] analytics library for all site
tags. For details, see [Adding Analytics > Setup][].
-[Adding Analytics > Setup]: https://www.docsy.dev/docs/adding-content/feedback/#setup
+[adding analytics > setup]:
+ https://www.docsy.dev/docs/adding-content/feedback/#setup
[v4.6.2 release notes]: https://github.com/twbs/bootstrap/releases/tag/v4.6.2
[docsy as an npm package]:
https://www.docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
@@ -125,31 +138,31 @@ Docsy now fetches Bootstrap and FontAwesome as NPM packages rather than git
submodules. This has an impact on your project-build setup. To migrate your
site, follow these steps (execute commands from your project's root directory):
- 1. Delete obsolete Docsy Git submodules:
- ```console
- $ rm -Rf themes/docsy/assets/vendor
- ```
- 2. Get Docsy dependencies:
- ```console
- $ (cd themes/docsy && npm install)
- ```
- 3. Update your build scripts to fetch Docsy dependencies automatically. For
- example, if your site build uses NPM scripts, consider getting Docsy
- dependencies via a [prepare][] script as follows:
- ```json
- {
- "name": "my-website",
- "scripts": {
- "prepare": "cd themes/docsy && npm install",
- "...": "..."
- },
+1. Delete obsolete Docsy Git submodules:
+ ```console
+ $ rm -Rf themes/docsy/assets/vendor
+ ```
+2. Get Docsy dependencies:
+ ```console
+ $ (cd themes/docsy && npm install)
+ ```
+3. Update your build scripts to fetch Docsy dependencies automatically. For
+ example, if your site build uses NPM scripts, consider getting Docsy
+ dependencies via a [prepare][] script as follows:
+ ```json
+ {
+ "name": "my-website",
+ "scripts": {
+ "prepare": "cd themes/docsy && npm install",
"...": "..."
- }
- ```
- 4. (Optional) Build script cleanup. If your project uses Docsy as a git
- submodule, Docsy updates no longer require the `--recursive` flag when
- running `git submodule update`. Consider dropping the flag if you have no
- other recursive git submodules.
+ },
+ "...": "..."
+ }
+ ```
+4. (Optional) Build script cleanup. If your project uses Docsy as a git
+ submodule, Docsy updates no longer require the `--recursive` flag when
+ running `git submodule update`. Consider dropping the flag if you have no
+ other recursive git submodules.
Proceed as usual to build or serve your site.
diff --git a/assets/scss/_boxes.scss b/assets/scss/_boxes.scss
index 562c77d5a5..f55c6c080b 100644
--- a/assets/scss/_boxes.scss
+++ b/assets/scss/_boxes.scss
@@ -77,26 +77,17 @@
// Styling for section boxes
.td-box {
- .row.section {
- padding-left: 5vw;
- padding-right: 5vw;
- flex-direction: column;
-
- > table {
- @extend .table-striped;
-
- @extend .table-responsive;
-
- @extend .table;
- }
- }
-
.row {
padding-left: 5vw;
padding-right: 5vw;
- flex-direction: row;
+ }
+ table {
+ @extend .table;
+ @extend .table-striped;
+ @extend .table-responsive;
}
}
+
// Styling for community page link boxes
.td-box.linkbox {
diff --git a/layouts/_default/content.html b/layouts/_default/content.html
index fac2253afd..ca8259310c 100644
--- a/layouts/_default/content.html
+++ b/layouts/_default/content.html
@@ -6,7 +6,7 @@
{{ .Title }}
{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
{{ partial "reading-time.html" . }}
{{ end }}
-
+
{{ .Content }}
{{ if (and (not .Params.hide_feedback) (.Site.Params.ui.feedback.enable) (.Site.GoogleAnalytics)) }}
{{ partial "feedback.html" .Site.Params.ui.feedback }}
@@ -18,3 +18,4 @@ {{ .Title }}
{{ end }}
{{ partial "page-meta-lastmod.html" . }}
+{{/**/ -}}
diff --git a/layouts/_default/list.html b/layouts/_default/list.html
index b2e137af6f..8362338e45 100644
--- a/layouts/_default/list.html
+++ b/layouts/_default/list.html
@@ -1,5 +1,3 @@
-{{ define "main" }}
-{{ with .Content }}
-{{ . }}
+{{ define "main" -}}
+{{ .Content -}}
{{ end }}
-{{ end }}
\ No newline at end of file
diff --git a/layouts/_default/search.html b/layouts/_default/search.html
index 2ea0a5c122..7025f80f9c 100644
--- a/layouts/_default/search.html
+++ b/layouts/_default/search.html
@@ -1,8 +1,8 @@
-{{ define "main" }}
+{{ define "main" -}}
{{ .Title }}
-{{ with .Site.Params.gcs_engine_id }}
+{{ with .Site.Params.gcs_engine_id -}}
-
-{{ end }}
+
+{{ end -}}
-
-{{ end }}
\ No newline at end of file
+{{ end }}
diff --git a/layouts/_default/single.html b/layouts/_default/single.html
index b2e137af6f..8362338e45 100644
--- a/layouts/_default/single.html
+++ b/layouts/_default/single.html
@@ -1,5 +1,3 @@
-{{ define "main" }}
-{{ with .Content }}
-{{ . }}
+{{ define "main" -}}
+{{ .Content -}}
{{ end }}
-{{ end }}
\ No newline at end of file
diff --git a/layouts/community/list.html b/layouts/community/list.html
index 1c8d2ffb2c..08e949e414 100644
--- a/layouts/community/list.html
+++ b/layouts/community/list.html
@@ -1,6 +1,6 @@
{{ define "main" -}}
-
+
diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html
index 1d68439d0d..6c12d62037 100644
--- a/layouts/shortcodes/blocks/lead.html
+++ b/layouts/shortcodes/blocks/lead.html
@@ -5,12 +5,13 @@
{{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}}
{{ end -}}
{{ end -}}
+
-{{/* Do NOT remove this comment! It ends above HTML block. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
{{ .Inner }}
diff --git a/layouts/shortcodes/blocks/section.html b/layouts/shortcodes/blocks/section.html
index ed61e7e2a5..fbe8f8c7ec 100644
--- a/layouts/shortcodes/blocks/section.html
+++ b/layouts/shortcodes/blocks/section.html
@@ -1,16 +1,14 @@
-{{ $_hugo_config := `{ "version": 1 }` -}}
{{ $col_id := .Get "color" | default .Ordinal -}}
{{ $height := .Get "height" | default "auto" -}}
-{{ $type := .Get "type" | default "" -}}
-
+{{ $type := .Get "type" | default "container" -}}
+
+
-
-
- {{ if eq .Page.File.Ext "md" -}}
- {{ .Inner | markdownify -}}
- {{ else -}}
- {{ .Inner | htmlUnescape | safeHTML -}}
- {{ end -}}
-
-
+
+
+{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ .Inner -}}
+
+
+{{/**/ -}}
diff --git a/userguide/content/en/_index.md b/userguide/content/en/_index.md
index 84f03c857b..8965d0a40b 100644
--- a/userguide/content/en/_index.md
+++ b/userguide/content/en/_index.md
@@ -27,7 +27,8 @@ on creating great content for your users.
{{% /blocks/lead %}}
-{{% blocks/section color="dark" type="features"%}}
+{{% blocks/section color="dark" type="row" %}}
+
{{% blocks/feature icon="fa-lightbulb" title="See Docsy in action!" url="/docs/examples/" %}}
As well as our example site, there's a growing number of projects using Docsy for their doc sites.
{{% /blocks/feature %}}
diff --git a/userguide/content/en/about/_index.md b/userguide/content/en/about/index.md
similarity index 97%
rename from userguide/content/en/about/_index.md
rename to userguide/content/en/about/index.md
index 8be99b5dc6..d92803f039 100644
--- a/userguide/content/en/about/_index.md
+++ b/userguide/content/en/about/index.md
@@ -2,7 +2,6 @@
title: About Docsy
linkTitle: About
menu: {main: {weight: 10}}
-layout: docs
---
{{% blocks/cover title="About Docsy" height="auto" %}}
@@ -12,7 +11,7 @@ Docsy is a pre-configured Hugo theme that provides the core features and behavio
Read on to find out more, or visit our [documentation](/docs/) to get started!
{{% /blocks/cover %}}
-{{% blocks/section type="section" color="primary" %}}
+{{% blocks/section color="primary" %}}
## So what’s a technical documentation site?
A technical documentation site is a website that your users can visit to find the documentation for your technical project. Your documentation set contains all the information you think your users might need to engage with your project, from overviews that help them understand what the project is for, to instructions for specific tasks. Depending on the size of the project, a documentation set can be a page or two or an entire “book” with different types of information.
@@ -28,7 +27,7 @@ If you have users around the world, you might also want to provide your content
Once you have your content, you use a technical documentation site to publish your technical documentation set online for your users. In addition to your documentation, your site might also contain material like contact information, a blog, or information about how to contribute to the project.
{{% /blocks/section %}}
-{{% blocks/section type="section" color="white" %}}
+{{% blocks/section color="white" %}}
## How does Docsy help?
Particularly when working with open source projects, it can be difficult to figure out how to turn all your product knowledge into a website that helps and engages your users. **Enter Docsy!**
@@ -122,7 +121,7 @@ template, or even add new behaviors. [Learn more...](/docs/updating/)
Because Docsy helps you create and serve a well-organized, navigable technical documentation set, it frees you up to create and maintain great reliable, comprehensive content that your users can enjoy and trust.
{{% /blocks/section %}}
-{{% blocks/section type="section" color="primary" %}}
+{{% blocks/section color="primary" %}}
## What's next for Docsy?
Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better. We hope to continue to make improvements to the theme along with the Docsy community.
@@ -130,8 +129,5 @@ Docsy is an open source project and we love getting patches and contributions to
Visit our [Issues](https://github.com/google/docsy/issues) to see what we're currently working on. If there's something you'd like to see in Docsy, please create an issue yourself - or assign yourself an issue if you'd like to fix or add something! See our [contribution guidelines](/docs/contribution-guidelines/) for more information.
You can find out how to update your site to the latest version of Docsy in [Keeping the theme up to date](/docs/updating/).
+
{{% /blocks/section %}}
-
-
-
-
diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md
index ef6ec3dd25..2b99b71d52 100644
--- a/userguide/content/en/docs/adding-content/shortcodes/index.md
+++ b/userguide/content/en/docs/adding-content/shortcodes/index.md
@@ -97,7 +97,7 @@ The example below shows a section wrapping 3 feature sections.
```go-html-template
-{{* blocks/section color="dark" */>}}
+{{* blocks/section color="dark" type="row" */>}}
{{%/* blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" */%}}
The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions.
Please follow this space for updates!
@@ -113,9 +113,9 @@ For announcement of latest features etc.
| Parameter | Default | Description |
| ---------------- |------------| ------------|
-| height | | See above.
-| color | | See above.
-| type | | Specify "section" if you want a general container, omit this parameter if you want this section to contain a horizontal row of features.
+| `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
diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml
index 54ef664b12..b95d4ce432 100644
--- a/userguide/hugo.yaml
+++ b/userguide/hugo.yaml
@@ -40,6 +40,9 @@ languages:
markup:
goldmark:
+ parser:
+ attribute:
+ block: true
renderer:
unsafe: true
highlight: