Skip to content

Latest commit

 

History

History
207 lines (141 loc) · 6.48 KB

METADOC-SHORTCODES.md

File metadata and controls

207 lines (141 loc) · 6.48 KB
Raw

Bottlerocket.dev Shortcodes

This site makes extensive use of Hugo shortcodes. Shortcodes help keep content away from logic. Some shortcodes are broadly useful and can be integrated into a variety of pages, while others are highly specific and only make sense on particular pages. The shortcodes can be found in the /layouts/shortcodes directory.

Current Shortcodes

all-settings.html

Usage: {{< all-settings >}}

Purpose: Create a list of all the settings in a given version of Bottlerocket. The version is extracted from the URL of the page. This is a single-purpose shortcode and is only really useful for the index of the settings reference.

bootstrap_containers_diagram.html

Usage: {{< bootstrap_containers_diagram example=n >}} (n is the example number)

Purpose: Show one of three diagrams on how bootstrap containers work. This is a single-purpose shortcode for /os/<ver>/concepts/bootstrap-containers/

center-button.html

Usage: {{< center-button link="<page>" label="<text>" lang="<lang code>" >}}

Purpose: Show a centered button in the homepage template. This is only useful for pages using the homepage template, but is specifically designed for future language redirection.

components_diagram.html

Usage:

{{< components_diagram <many, many arguments> >}}

Purpose: This is a wrapper around the SVG diagrams on /os/<ver>/concepts/components/ page. It allows you to change the labels of the components or enable/disable boxes. It has a very specific use-case, but it is used on multiple pages.

faqlist.html

Usage:

{{< faqlist >}}

Purpose: To render the FAQ. It's only used on /faq but it will be useful for localization.

kernel-variant-info.html

Usage: {{< kernel-variant-info >}}

Purpose: To render the kernel information about variants. Only used on /version-information/variants

latest-redirect.html

Usage: {{< latest-redirect >}}

Purpose: To redirect hash links to the latest version. It's only used on latest.markdown. This provides functionality to have evergreen links through a Javascript redirect. So, for example: https://bottlerocket.dev/en/os/latest/#/api/settings/container-runtime/ will always redirect to the latest version of the docs for container runtime. The usage of this type of linking should be used judiciously as the redirect doesn't pass search engine traffic.

nav-bar-open.html

Usage: {{< nav-bar-open html_id="m-enos-check" >}}

Purpose: This is used on the main documentation (/en) page to inject Javascript that "opens" the sidebar menu to the latest version based on a tag ID. It could be useful on other pages, but it's likely only needed to direct the reader to the most recent page.

os-release-example.html

Usage: {{< os-release-example orchestrator="k8s" build_id="6ef1139f" >}}

Purpose: This is used on the quickstart host container page as a way to keep the output mockup fresh per version. It has no other use.

packages-by-variant.html

Usage: {{< packages-by-variant >}}

Purpose: This renders the grid of packages included in each variant on /version-information/packages-by-variant/ only. It has no other use.

packages-table.html

Usage: {{< packages-table >}}

Purpose: This renders the table of packages included in a particular version. It has no other use and the page that uses this shortcode is generated.

page-ver.html

Usage:

{{< page-ver >}}

Purpose: This injects information about the version docs being viewed into a scratch variable. Independently, this has no rendered output but can be used to support other shortcodes. Currently, it is only used with kernel-variant-info although it could be used with others.

setting-reference.html

Usage: {{< setting-reference setting="" >}}{{</ setting-reference >}}

Purpose: This can be used to create a link to setting reference documentation. For many settings, especially those with complicated names, creating a link to the reference is not straightforward. This provides an easier way to render this, by supplying the rendered setting text in the setting argument.

settings.html

Usage: {{< settings >}}

Purpose: This renders the entire setting reference and is used on every setting reference category (e.g. /api/settings/*) The parameters are derived from the called page, no other arguments are needed.

stackedfigure.html

Usage:

{{< stackedfigure  alt="" src="" caption="" >}} 
...sometimes other stuff..
{{</ stackedfigure>}}

Purpose: This shortcode provides a common way to have a chart/diagram with a caption below it. If supplied src and alt it will render add an image tag. If not it will use the "other stuff" between the opening and closing template tag.

subsections-list.html

Usage: {{< subsections-list >}}

Purpose: Renders a list of the subsections in a given section. It is used only at the root of a section (e.g. os) to generate a reverse chronological list of versions.

twocol.html & twocol_inner.html

Usage:

{{< twocol containerclass="" rowclass="">}}
    {{< twocol_inner colsplit="" >}}.. stuff ..{{</ twocol_inner >}}
    {{< twocol_inner colsplit="" >}}.. stuff ..{{</ twocol_inner >}}
{{< /twocol >}}

Purpose: Create a side-by-side chat with details. Each twocol_inner containes the content.

twocolfigure.html

Usage:

{{< twocolfigure colsplit="" alt="" caption="" >}}
    .. stuff ..
{{</ twocolfigure>}}

Purpose: Every similar to twocol/twocol_inner shortcodes (actually an earlier version). It creates a two column, responsive layout with one side being content via the caption. This is only used on the homepage.

ver-ref.html

Usage::

{{< ver-ref project="" page="" >}} ... {{< /ver-ref >}}

Purpose: This creates links with proper the current version and language references without relying on relative links (avoiding relative links in Hugo is a best practice). project is usually os (for Bottlerocket OS) and page is the is the path of the page of the content (note that the path does not include the trailing slash or extension). So, for example, to link to /<lang>/os/<version>/concepts/variants/ the shortcode would be something like: {{< ver-ref project="os" page="/concepts/variants" >}}Variants{{< /ver-ref >}}, which will make a link to a path like /en/os/1.16.x/concepts/variants/.