{"id":14981372,"url":"https://github.com/chipzoller/hugo-clarity","last_synced_at":"2025-05-14T23:07:21.765Z","repository":{"id":37242875,"uuid":"256256206","full_name":"chipzoller/hugo-clarity","owner":"chipzoller","description":"A theme for Hugo based on VMware Clarity","archived":false,"fork":false,"pushed_at":"2025-05-14T18:54:51.000Z","size":6376,"stargazers_count":619,"open_issues_count":34,"forks_count":275,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-14T19:47:35.762Z","etag":null,"topics":["blog","blog-theme","hugo","hugo-theme","personal-site"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chipzoller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-16T15:31:58.000Z","updated_at":"2025-05-14T18:54:56.000Z","dependencies_parsed_at":"2023-02-10T21:45:19.552Z","dependency_job_id":"a694c99c-8d4b-49e5-b2ca-7fe160a42d73","html_url":"https://github.com/chipzoller/hugo-clarity","commit_stats":{"total_commits":788,"total_committers":65,"mean_commits":"12.123076923076923","dds":0.6269035532994924,"last_synced_commit":"174847b47d1192aea2a2f2ba9580aba4064c9773"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipzoller%2Fhugo-clarity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipzoller%2Fhugo-clarity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipzoller%2Fhugo-clarity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipzoller%2Fhugo-clarity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chipzoller","download_url":"https://codeload.github.com/chipzoller/hugo-clarity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243362,"owners_count":22038046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog","blog-theme","hugo","hugo-theme","personal-site"],"created_at":"2024-09-24T14:03:24.789Z","updated_at":"2025-05-14T23:07:16.754Z","avatar_url":"https://github.com/chipzoller.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hugo Clarity Theme\n\nA technology-minded theme for Hugo based on VMware's open-source [Clarity Design System](https://clarity.design/) featuring rich code support, dark/light mode, mobile support, and much more. See [a live demo at __neonmirrors.net__](https://neonmirrors.net/).\n\n![Clarity Hugo Theme](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/images/screenshot.png)\n\n## Preview on Desktop\n\n| Light Mode                                                                                                        | Dark Mode                                                                                                                 |\n| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ![Clarity Hugo Theme desktop light](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/images/screenshot.png) | ![Clarity Hugo Theme desktop dark](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/images/screenshot-darkmode.png) |\n\n## Preview on Mobile\n\n| Light Mode                                                                                                              | Dark Mode                                                                                                                       |\n| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| ![Clarity Hugo Theme mobile light](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/images/screenshot-mobile.png) | ![Clarity Hugo Theme mobile dark](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/images/screenshot-mobile-darkmode.png) |\n\n## Table of Contents\n\n* [Features](#features)\n* [Prerequisites](#prerequisites)\n* [Getting up and running](#getting-up-and-running)\n* [Configuration](#configuration)\n  * [Global Parameters](#global-parameters)\n  * [Page Parameters](#page-parameters)\n  * [Menus](#modify-menus)\n    * [Main Menu](#main-menu)\n    * [Social media](#social-media)\n  * [Search Engine](#search-engine)\n  * [Blog directory](#blog-directory)\n  * [Mobile menu positioning](#mobile-menu-positioning)\n  * [Tags and taxonomies](#tags-and-taxonomies)\n  * [Images](#images)\n    * [Organizing page resources](#organizing-page-resources)\n    * [Modern image formats](#support-for-modern-image-formats)\n    * [Image captions](#image-captions)\n    * [Adding figure positions to image captions](#adding-figure-positions-to-image-captions)\n    * [Inline images](#inline-images)\n    * [Floating images](#float-images-to-the-left)\n    * [Round borders](#round-borders-for-images)\n    * [Adding CSS classes](#add-classes-to-images)\n    * [Featured image](#featured-image)\n    * [Thumbnail image](#thumbnail-image)\n    * [Share image](#share-image)\n    * [Logo alignment](#logo-alignment)\n  * [Code](#code)\n  * [Table of contents](#table-of-contents-1)\n  * [Pinning featured posts](#pinning-featured-posts)\n  * [Notices](#notices)\n  * [Custom CSS and JS](#custom-css-and-js)\n  * [Custom Site Disclaimer](#site-disclaimer)\n  * [Forcing light or dark mode](#forcing-light-or-dark-mode)\n  * [Internationalization - I18N](#i18n)\n  * [Hooks](#hooks)\n  * [Comments](#comments)\n  * [Math notation](#math-notation)\n  * [Open Street Map](#map)\n  * [Search](#search)\n* [Contributing](#contributing)\n* [Code of conduct](#code-of-conduct)\n* [License](#license)\n\n## Features\n\n* Blog with tagging and category options\n\n* Search\n\n* Deeplinks\n\n* Choice of whether to use [Hugo Page Bundles](https://gohugo.io/content-management/page-bundles/)\n\n* Native image lazy-loading\n\n* Customizable (see config)\n\n* Dark mode (with UI controls for user preference setting)\n\n* Toggleable table of contents\n\n* Toggleable automatic figure numbering\n\n* Configurable site disclaimer (i.e. \"my views are not my employer's\")\n\n* Flexible image configuration, and support for modern formats like WebP\n\n* Logo alignment\n\n* Mobile support with configurable menu alignment\n\n* Syntax highlighting\n\n* Rich code block functions including:\n\n  1. Copy to clipboard\n\n  2. Toggle line wrap (dynamic)\n\n  3. Toggle line numbers\n\n  4. Language label\n\n  5. Toggle block expansion/contraction (dynamic)\n\n     To put it all in context, here is a preview showing all functionality.\n\n     ![code block functions](https://github.com/chipzoller/hugo-clarity/blob/master/images/syntax-block.gif)\n\n## Prerequisites\n\nFirstly, __ensure you have installed the [extended version of Hugo 0.91.0 or above](https://github.com/gohugoio/hugo/releases)__. See installation steps from [Hugo's official docs](https://gohugo.io/getting-started/installing/) for more information. Note that software repositories may be several versions behind and may not include the extended version.\n\n## Getting up and running\n\nRead the [prerequisites](#prerequisites) above and verify you're using the __extended version of Hugo 0.91.0 or newer__.\n\nThere are several ways to use this theme:\n\n### Option 1a: Development in the browser\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/chipzoller/hugo-clarity)\n\nFor trying out the theme, quick experimentation, and to contribute Pull Requests, Gitpod is the easiest option. Use the button above and it will spin up a prebuilt environment with a site ready to go.\n\nIf you want to contribute a PR, [this is a good overview of that process](https://jldec.me/using-gitpod-to-create-a-pr), and there's also an [optional browser extension](https://www.gitpod.io/docs/browser-extension). [Read more about contributing to Hugo Clarity](CONTRIBUTING.md)\n\n### Option 1b: Development on your machine\n\nIf you prefer not to use Gitpod, you can also test, develop and contribute PRs locally from your computer.\n\n```bash\ngit clone https://github.com/chipzoller/hugo-clarity\ncd hugo-clarity/exampleSite/\nhugo server --themesDir ../..\n```\n\n\u003e Note that while this is a good way to work on Hugo Clarity, isn't a good way to work on your own site, since it uses the content from `exampleSite`, and wouldn't be aware of any overrides your site might apply to the theme.\n\n[Read more about contributing to Hugo Clarity](CONTRIBUTING.md)\n\n### Option 2: Hugo modules\n\nThis option arguably requires the least effort to run and maintain your website with the Hugo Clarity theme.\n\nWe assume you've already run `hugo new site \u003csitename\u003e` and are in the `\u003csitename\u003e` directory.\n\n1. Ensure you have the `go` binary [installed on your machine](https://golang.org/doc/install). (Mac users: ```brew install go```.)\n\n2. Run the following command:\n```bash\nhugo mod init \u003csitename\u003e\n```\n\n3. Hugo Clarity comes with [`exampleSite` files](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite) prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing:\n```bash\nwget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz \u0026\u0026 cp -a hugo-clarity-master/exampleSite/* . \u0026\u0026 rm -rf hugo-clarity-master \u0026\u0026 rm -f config.toml\n```\nIf you are using PowerShell, paste this instead:\n```bash\nwget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz -and cp -a hugo-clarity-master/exampleSite/* . -and rm -rf hugo-clarity-master -and rm -f config.toml\n```\nIf you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of [`config`](exampleSite/config/) over, as well as replacing your `archetypes/post.md` (if it exists) with [Hugo Clarity's](exampleSite/archetypes/post.md). Then migrate any necessary settings from `\u003csitename\u003e/config.toml` to `\u003csitename\u003e/config/_default/config.toml` and remove the original `\u003csitename\u003e/config.toml` file.\n\n4. Open `\u003csitename\u003e/config/_default/config.toml` and change `theme = \"hugo-clarity\"` to `theme = [\"github.com/chipzoller/hugo-clarity\"]`\n\n5. You can now run:\n```bash\nhugo server\n```\n\nIf that seems like a lot of setup, it's meant to reduce the pain of pulling in new versions of Hugo Clarity when they are released.\n\nTo pull in theme updates, run `hugo mod get -u github.com/chipzoller/hugo-clarity`. You can also update all your Hugo modules with `hugo mod get -u ./...` -- [read more about updating Hugo modules](https://gohugo.io/hugo-modules/use-modules/#update-modules).\n\n\u003e There is [more you can do with hugo modules](https://github.com/rootwork/hugo-module-site), but this will suffice for our use case here.\n\n### Option 3: Git submodules\n\nFor those not ready to use Hugo modules, you can use the \"old way\" using git alone.\n\nWe assume you've already run `hugo new site \u003csitename\u003e`, are in the `\u003csitename\u003e` directory, and have a working git repo (`git init`).\n\n1. Run:\n```bash\ngit submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity\n```\n\n2. Hugo Clarity comes with [`exampleSite` files](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite) prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing:\n```bash\ncp -a themes/hugo-clarity/exampleSite/* . \u0026\u0026 rm -f config.toml\n```\nIf you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of [`config`](exampleSite/config/) over, as well as replacing your `archetypes/post.md` (if it exists) with [Hugo Clarity's](exampleSite/archetypes/post.md). Then migrate any necessary settings from `\u003csitename\u003e/config.toml` to `\u003csitename\u003e/config/_default/config.toml` and remove the original `\u003csitename\u003e/config.toml` file.\n\n3. You can now run:\n```bash\nhugo server\n```\n\nWhile this is less setup than option 2 initially, it comes with important caveats. First, to pull in new versions of the theme, you'll need to run `git submodule update --remote --merge` _and commit those changes to your git repo_. Second, if you clone your repo to another machine, have multiple people working on your site, or have a continuous-integration or deployment script (like Netlify), after cloning you'll need to also remember to run `git submodule update --init --recursive` to get the theme files.\n\nSee [an overview of using git submodules for Hugo themes](https://www.andrewhoog.com/post/git-submodule-for-hugo-themes/) and [troubleshooting git submodules in Hugo themes](https://study.impl.dev/hacking/git-submodule-hugo-theme/) for details.\n\n## Configuration\n\nHugo Clarity uses a config folder rather than a single file. If you're used to having a `config.toml` file in your main folder, now you'll find that located in `config/_default/config.toml`, along with other settings files.\n\nThis section will mainly cover settings that are unique to this theme. If something is not covered here (or elsewhere in this file), there's a good chance it is covered in [this Hugo docs page](https://gohugo.io/getting-started/configuration/#configuration-file).\n\n### Global Parameters\n\nThese options set global values that some pages or all pages in the site use by default.\n\n| Parameter                  | Value Type                  | Overridable on Page |\n|:-------------------------- | --------------------------- | ------------------- |\n| author                     | map / string                | no                  |\n| twitter                    | string                      | no                  |\n| largeTwitterCard           | boolean                     | no                  |\n| ga_analytics               | string                      | no                  |\n| google_tag_manager_id      | string                      | no                  |\n| baidu_analytics            | string                      | no                  |\n| plausible_analytics        | boolean                     | no                  |\n| matomo_analytics           | boolean                     | no                  |\n| umami_data_website_id      | string                      | no                  |\n| description                | string                      | yes                 |\n| keywords                   | array of strings            | yes                 |\n| introDescription           | string                      | yes                 |\n| introURL                   | string/false                | no                  |\n| numberOfTagsShown          | integer                     | no                  |\n| usePageBundles             | boolean                     | yes                 |\n| fallBackOgImage            | file path (string)          | no                  |\n| codeMaxLines               | integer                     | yes                 |\n| codeLineNumbers            | boolean                     | yes                 |\n| mainSections               | array/string                | no                  |\n| centerLogo                 | boolean                     | no                  |\n| logo                       | file path (string)          | no                  |\n| iconsDir                   | dir path (string)           | no                  |\n| mobileNavigation           | string                      | no                  |\n| figurePositionShow         | boolean                     | yes                 |\n| figurePositionLabel        | string                      | no                  |\n| customCSS                  | array of file path (string) | no                  |\n| customJS                   | array of file path (string) | no                  |\n| enforceLightMode           | boolean                     | N/A                 |\n| enforceDarkMode            | boolean                     | N/A                 |\n| titleSeparator             | string                      | no                  |\n| showShare                  | boolean                     | yes                 |\n| comments                   | boolean                     | yes                 |\n| numberOfRecentPosts        | integer                     | no                  |\n| numberOfFeaturedPosts      | integer                     | no                  |\n| pinFeatured                | boolean                     | no                  |\n| numberOfPinnedPosts        | integer                     | no                  |\n| dateFormat                 | string                      | no                  |\n| enableMathNotation         | boolean                     | yes                 |\n| customFonts                | boolean                     | no                  |\n| since                      | integer                     | N/A                 |\n| rss_summary                | boolean                     | N/A                 |\n| rss_summary_read_more_link | boolean                     | N/A                 |\n| showRelatedInArticle       | boolean                     | yes                 |\n| showRelatedInSidebar       | boolean                     | no                  |\n| footerLogo                 | string                      | N/A                 |\n| enableSearch               | boolean                     | N/A                 |\n| blogDir                    | string                      | no                  |\n| cdn                        | map                         | no                  |\n\n### Page Parameters\n\nThese options can be set from a page [frontmatter](https://gohugo.io/content-management/front-matter#readout) or via [archetypes](https://gohugo.io/content-management/archetypes/#readout).\n\n| Parameter            | Value Type         | Overrides Global |\n|:-------------------- | ------------------ | ---------------- |\n| title                | string             | N/A              |\n| date                 | date               | N/A              |\n| lastmod              | date               | N/A              |\n| description          | string             | N/A              |\n| keywords             | array of strings   | yes              |\n| introDescription     | string             | yes              |\n| abstract             | string             | N/A              |\n| summary              | string             | N/A              |\n| draft                | boolean            | N/A              |\n| featured             | boolean            | N/A              |\n| tags                 | array/string       | N/A              |\n| categories           | array/string       | N/A              |\n| toc                  | boolean            | N/A              |\n| usePageBundles       | boolean            | yes              |\n| featureImage         | file path (string) | N/A              |\n| featureImageAlt      | string             | N/A              |\n| featureImageCap      | string             | N/A              |\n| thumbnail            | file path (string) | N/A              |\n| shareImage           | file path (string) | N/A              |\n| codeMaxLines         | integer            | yes              |\n| codeLineNumbers      | boolean            | yes              |\n| figurePositionShow   | boolean            | yes              |\n| figurePositionLabel  | string             | no               |\n| comments             | boolean            | yes              |\n| enableMathNotation   | boolean            | yes              |\n| showDate             | boolean            | N/A              |\n| showLastmod          | boolean            | N/A              |\n| lastmodSeparator     | string             | N/A              |\n| showShare            | boolean            | N/A              |\n| showReadTime         | boolean            | N/A              |\n| sidebar              | boolean            | N/A              |\n| singleColumn         | boolean            | N/A              |\n| showRelatedInArticle | boolean            | N/A              |\n| noindex              | boolean            | N/A              |\n\n### Modify Menus\n\n#### Main Menu\n\nTo add, remove, or reorganize top menu items, [edit the files here](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite/config/_default/menus). Specifically look for items with `[[main]]`.\n\nIf you prefer the more [traditional approach](https://gohugo.io/content-management/menus/#readout), delete `content\\config` folder and enter a [main menu entry](https://gohugo.io/content-management/menus/#add-non-content-entries-to-a-menut) inside the `config.toml` file\n\n#### Social media\n\nTo edit your social media profile links, edit the files referenced above. Specifically, look for items with `[[social]]`\n\nIf you wish to globally use a [large Twitter summary card](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/summary-card-with-large-image) when sharing posts, set the global parameter `largeTwitterCard` to `true`.\n\n### Web site analytics\n\nIf using Google Analytics, configure the `ga_analytics` global parameter in your site with your ID. You can opt to set a google tag manager using `google_tag_manager_id`.\n\nIf using Baidu Analytics, configure the `baidu_analytics` global parameter in your site with your ID.\n\nIf using Plausible Analytics, configure the `plausible_analytics` global parameters in your site with the following.\n\n`enable` To enable plausible analytics change to `true`.\n\n`websiteDomain` Set domain name of your website, most cases same as your base URL this is required.\n\n`plausibleDomain`  Default is set to plausible.io, this parameter is only required if plausible is self-hosted.\n\n`scriptName`  Default is set to plausible, this parameter is only required if using a custom name for script.\n\nIf using Matomo Analytics, configure the `matomo_analytics` global parameters in your site with the following.\n\n`enable` To enable matomo analytics change to `true`.\n\n`websiteDomain` Set the domain name of your website, in most cases same as your base URL this is required.\n\n`matomoDomain`   Set to Matomo domain\n\n`matomoSiteID`  Default is set to 1, change this to the siteid being tracked\n\nIf using [Umami Analytics](https://umami.is/), uncomment and configure the following in *params.toml*:\n\n* `umami_data_website_id` - The data website ID provided in the script by Umami.  It should be in the form of a GUID (# characters):  8-4-4-4-12.\n* `umami_script_url` - This is pre-loaded with the cloud-hosted Umami Script URL, but can be changed if you are self-hosting.\n\n\u003e NOTE:  The head partial only loads analytics if the hugo environment is NOT `development`.  \n\n### Blog directory\n\nEdit `params.toml` and change the `mainSections` key. Values will be directories where the blogs reside.\n\n```yaml\n...\nmainSections = [\"posts\", \"docs\", \"blogs\"]\n...\n```\n\nFor more info, see the [Hugo docs](https://gohugo.io/functions/where/#mainsections).\n\n### Mobile menu positioning\n\nThe navigation menu when mobile browsing can be configured in `config.toml` to open right or left depending on preference. The \"hamburger\" menu icon will always display in the upper right hand corner regardless.\n\n```yaml\n[params]\n...\nmobileNavigation = \"left\" # Mobile nav menu will open to the left of the screen.\n...\n```\n\n### Tags and Taxonomies\n\n#### Show number of tags\n\nThe number of tags and taxonomies (including categories) that should be shown can be configured so that any more than this value will only be accessible when clicking the All Tags button. This is to ensure a large number of tags or categories can be easily managed without consuming excess screen real estate. Edit the `numberOfTagsShown` parameter and set accordingly.\n\n```yaml\n[params]\n...\nnumberOfTagsShown = 14 # Applies for all other default \u0026 custom taxonomies. e.g categories, brands see https://gohugo.io/content-management/taxonomies#what-is-a-taxonomy\n...\n```\n\n#### Number of tags example\n\n![Tags](https://github.com/chipzoller/hugo-clarity/blob/master/images/tags.png)\n\n### Images\n\nA number of CSS classes are automatically added to images based on their source or type to aid you in any tweaks to the theme. These include:\n\n- `image_figure` when the image appears inside a `\u003cfigure\u003e` element\n- `image_internal` when the image is local, within the site\n- `image_external` when the image is loaded from a URL\n- `image_processed` when the image has been passed through [Hugo Pipes](https://gohugo.io/hugo-pipes/introduction/) (requires the image to be using page bundles or be in the `assets` directory)\n- `image_unprocessed` when the image has not been passed through Hugo Pipes\n- `image_thumbnail` when the image is in a list of content excerpts\n- `image_featured` when the image is a banner or hero image at the top of a post\n- `image_svg` when the image is an [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) (and thus [cannot be run through Hugo Pipes](https://github.com/gohugoio/hugo/issues/3700))\n\nMost images in Hugo Clarity are loaded [lazy](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading#images_and_iframes) and [asynchronously](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decoding) to improve site speed. Images that are not loaded in this manner include the site's logo.\n\nImages, whether used within Markdown content or using parameters like `featureImage` or `thumbnail`, can be local or remote images. Remote images (starting with `http...`) will automatically be downloaded, stored and optimized by Hugo Clarity, so that the finished site will only serve local images.\n\n#### Organizing page resources\n\nBy default, Hugo Clarity assumes that page resources -- images and other related files -- are stored in the `static` or `assets` directories. Alternatively, you can opt-in to using [Hugo page bundles](https://gohugo.io/content-management/page-bundles/) by setting the `usePageBundles` option to `true` in your site parameters. Using this method, you keep a post's assets in the same directory as the post itself.\n\nIf you have an existing site that is not using page bundles but would like to start with new posts, `usePageBundles` can be overridden at the post level in the front matter. If it is not set in the post, it will default to the site's parameter. Take a look at [`exampleSite/content/post/bundle/index.md`](exampleSite/content/post/bundle/index.md) for more information and an example of overriding this setting on an individual post.\n\n#### Support for modern image formats\n\nIf you are using page bundles (see above) and reference `sample.jpg` in your post, Hugo Clarity will check to see if the same image (based on filename) exists in the modern formats of [WebP](https://en.wikipedia.org/wiki/WebP), [AVIF](https://en.wikipedia.org/wiki/AVIF) or [JXL](https://en.wikipedia.org/wiki/JPEG_XL). If it does, these will be presented to browsers as alternative options. Browsers that [support these formats and the `\u003cpicture\u003e` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#the_type_attribute) will load them, while browsers that do not will fall-back to the default image.\n\nNote that this does not *create* the other versions of the image for you, it simply checks to see if they exist. You may want to automate this process in your site build; [here is one example](https://github.com/rootwork/rootwork.org/blob/main/scripts/image_optimize.sh).\n\n#### Image captions\n\nImage captions are automatically generated. If an image has title text, the caption will be created from it; if an image has no title text, the alt text will be used. To display an image with alt text but no caption, use title text of a single space (`\" \"`).\n\nExamples of captions:\n\n- `![Jane Doe](../images/jane-doe.png)` will display the local `jane-doe.png` image with a caption of \"Jane Doe\".\n- `![Jane Doe](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/exampleSite/static/images/jane-doe.png \"This is Jane Doe\")` will display the remote image `jane-doe.png` with a caption of \"This is Jane Doe\".\n- `![A building](../images/building.png \" \")` will display the local image `building.png` with no caption.\n\nExamples of this can also be found in the \"Markdown Syntax Guide\" post in the example site content.\n\n\u003e NOTE: Due to limitations in Markdown, single and double quotes should not be used within alt or title text.\n\n#### Adding figure positions to image captions\n\nYou have the option of prepending a desired string such as \"Figure N\" to the caption text of images within an article's content.\n\nTwo global settings control this feature:\n\n- `figurePositionLabel` is a string which will be prepended to any caption text of an article image; by default this is set to \"Figure\".\n- `figurePositionShow` controls, globally, whether to show this label. (It does not affect the visibility of image captions in general, only the prepended figure position text.) For more granular control, `figurePositionShow` can be overridden at the article level if desired.\n\nFigure numbers will be automatically inserted after the `figurePositionLabel` text, starting from the top of the article and increasing as you move down.\n\n#### Example of image with figure positions added\n\nAssume that `figurePositionLabel` is set to \"Figure\" in `config.toml` and this is the first image in a given article.\n\n```markdown\n![A schematic for using Antrea with Kubernetes](./images/image-figure.png \"Antrea Kubernetes nodes prepared\")\n```\n\n![Figure captioning example](https://github.com/chipzoller/hugo-clarity/blob/master/images/image-figure.png)\n\n#### Inline images\n\nTo make an image inline, append `:inline` to its alt text.\n\n#### Inline images example\n\n```markdown\n\u003c!-- an inline image without alt text --\u003e\n\n![:inline](someImageUrl)\n\n\u003c!-- an inline image with alt text --\u003e\n\n![text describing the image:inline](someOtherImageUrl)\n```\n\n![Inline image example](https://github.com/chipzoller/hugo-clarity/blob/master/images/image-inline.png)\n\n#### Float images to the left\n\nTo align a blog image to the left, append `:left` to its alt text. Article text will then flow to the right of the image.\n\n#### Float images left example\n\n```markdown\n\u003c!-- a left-floated image without alt text --\u003e\n\n![:left](someImageUrl)\n\n\u003c!-- a left-floated image with alt text --\u003e\n\n![text describing the image:left](someOtherImageUrl)\n```\n\n#### Float images to the right\n\nTo align a blog image to the right, append `:right` to its alt text. Article text will then flow to the left of the image.\n\n#### Float images right example\n\n```markdown\n\u003c!-- a right-floated image without alt text --\u003e\n\n![:right](someImageUrl)\n\n\u003c!-- a right-floated image with alt text --\u003e\n\n![text describing the image:right](someOtherImageUrl)\n```\n\n#### Round borders for images\n\nTo make the image borders round, append `::round` to its alt text. This is a\npre-defined image class commonly used to display portrait images. Note that round\nis just another class and it can be mixed with other classes separated by space.\n\n#### Round borders for images example\n\n```markdown\n\u003c!-- an image without alt text and round borders--\u003e\n\n![::round](someImageUrl)\n\n\u003c!-- an image with alt text and round borders--\u003e\n\n![text describing the image::round](someOtherImageUrl)\n\n\u003c!-- a left-floating image without alt text and with round borders--\u003e\n\n![:left::round](someOtherImageUrl)\n```\n\n#### Add classes to images\n\nTo add a CSS class to an image, append `::\u003cclassname\u003e` to its alt text. You can also add multiple classes to an image separated by space. `::\u003cclassname1\u003e \u003cclassname2\u003e`.\n\n#### Image classes example\n\n```markdown\n\u003c!-- an image without alt text --\u003e\n\n![::img-medium](someImageUrl)\n\n\u003c!-- an image with alt text --\u003e\n\n![text describing the image::img-large img-shadow](someOtherImageUrl)\n```\n\n#### Featured image\n\nEach article can specify an image that appears at the top of the content.\n\n```yaml\n...\nfeatureImage: \"images/2020-04/capv-overview/featured.jpg\"\n...\n```\n\nThe path for the featured image is relative to the `static` directory if not using [Page Bundles](#organizing-page-resources), and relative to the post's own directory if using them.\n\nTwo other frontmatter settings allow you to set alt text for the featured image and an optional caption.\n\n```yaml\n...\nfeatureImageAlt: 'Text describing the featured image' # Alternative text for featured image.\nfeatureImageCap: 'A caption appearing below the image.' # Caption (optional).\n...\n```\n\nUnless specified using `featureImageCap`, a caption will not be generated for the featured image.\n\n#### Thumbnail image\n\nEach article can specify a thumbnail image which will be displayed on the left of the article's card on the home page and in lists of articles.\n\n```yaml\n...\nthumbnail: \"images/2020-04/capv-overview/thumbnail.jpg\"\n...\n```\n\nThumbnails look best when square (height:width ratio of 1:1) and at least 150x150 pixels.\n\nThe path for the thumbnail image is relative to the `static` directory if not using [Page Bundles](#organizing-page-resources), and relative to the post's own directory if using them.\n\n#### Share image\n\nEach article can specify a share image which will used when the article is shared on social media.\n\n```yaml\n...\nshareImage: \"images/theImageToBeUsedOnShare.png\"\n...\n```\n\nIf a share image is not specified, the order of precedence that will be used to determine which image applies is `thumbnail` =\u003e `featureImage` =\u003e `fallbackOgImage`. That is, if no thumbnail is specified, the featured image will be used; if neither is specified, the fallback image will be used.\n\nWhen sharing a link to the home page of the site (as opposed to a specific article), the `fallbackOgImage` will be used.\n\nThe path for the share image is relative to the `static` directory if not using [Page Bundles](#organizing-page-resources), and relative to the post's own directory if using them.\n\n#### Logo alignment\n\nYou can left align or center your site's logo.\n\n```yaml\n...\ncenterLogo = true # Change to false to align left\n...\n```\n\nIf no logo is specified, the title of the site will appear in its place.\n\n### Code\n\n#### Display line numbers\n\nChoose whether to display line numbers within a code block globally with the parameter `codeLineNumbers` setting to `true` or `false`.\n\n```yaml\n[params]\n...\ncodeLineNumbers = true # Shows line numbers for all code blocks globally.\n...\n```\n\n#### Limit code block height\n\nYou can globally control the number of lines which are displayed by default for your code blocks. Code which has the number of lines exceed this value will dynamically cause two code block expansion buttons to appear, allowing the user to expand to full length and contract. This is useful when sharing code or scripts with tens or hundreds of lines where you wish to control how many are displayed. Under params in `config.toml` file, add a value as follows:\n\n```yaml\n[params]\n...\ncodeMaxLines = 10 # Maximum number of lines to be shown by default across all articles.\n...\n```\n\n\u003e If the value already exists, change it to the desired number. This will apply globally.\n\nIf you need more granular control, this parameter can be overridden at the blog article level. Add the same value to your article frontmatter as follows:\n\n```yaml\n...\ncodeMaxLines = 15 # Maximum number of lines to be shown in code blocks in this blog post.\n...\n```\n\nIf `codeMaxLines` is specified both in `config.toml` and in the article frontmatter, the value specified in the article frontmatter will apply to the given article. In the above example, the global default is `10` and yet the article value is `15` so code blocks in this article will auto-collapse after 15 lines.\n\nIf `codeMaxLines` is not specified anywhere, an internal default value of `100` will be assumed.\n\n#### Line Highlighting\n\nIt is possible to highlight specific lines in a code block by applying `{hl_lines=[7]}` after the fence and language. For example, the below snippet will highlight lines 7 and 8 in the code block to which it is applied.\n\n```\n```yaml {hl_lines=[7,8]}\n```\n\nRanges are also supported by quoting the range inside the braces.\n\n```\n```yaml {hl_lines=[\"7-18\"]}\n```\n\n### Table of contents\n\nEach article can optionally have a table of contents (TOC) generated for it based on top-level links. By configuring the `toc` parameter in the article frontmatter and setting it to `true`, a TOC will be generated only for that article. The TOC will then render under the featured image.\n\n#### Table of contents (TOC) example\n\n![Article table of contents](https://github.com/chipzoller/hugo-clarity/blob/master/images/article-toc.png)\n\n### Pinning featured posts\n\nThis allows you to show the featured posts at the top of the post list.\n\nUse the [site configuration option](#global-parameters) `pinFeatured` to enable/disable it, and the option `numberOfPinnedPosts` to control how many posts to be pinned.\n\n### Custom CSS and JS\n\nTo minimize HTTP requests per page, we would recommend loading CSS styles and JavaScript helpers in single bundles. That is to say, one CSS file and one JavaScript file. Using Hugo minify functions, these files will be minified to optimize the size.\n\nGoing by the above 👆🏻 reason, we recommend adding custom CSS and JS via these files:\n\n1. [`_override.sass`](https://github.com/chipzoller/hugo-clarity/blob/master/assets/sass/_override.sass).\n    This file should only be used to override sass \u0026 css variables e.g theme colors\n2. [`_custom.sass`](https://github.com/chipzoller/hugo-clarity/blob/master/assets/sass/_custom.sass).\n    This file should only be used to override everything else except sass \u0026 css variables.\n3. [`custom.js`](https://github.com/chipzoller/hugo-clarity/blob/master/assets/js/custom.js).\n\n\u003e __Pro Tip__: Ensure that your changes are git trackable by creating these files outside the theme directory. That is, at the root level of your site's directory. See tree below.\n\n```\n├── yourSite\n│   ├── archetypes\n│   │   └── post.md\n│   ├── assets\n│   │   ├── js\n│   │   │   └── custom.js\n│   │   └── sass\n│   │       ├── _custom.sass\n│   │       └── _override.sass\n│   ├── config\n│   │   └── _default\n│   │       ├── config.toml\n│   │       ├── configTaxo.toml\n│   │       ├── languages.toml\n│   │       ├── markup.toml\n│   │       ├── menus\n│   │       │   ├── menu.en.toml\n│   │       │   └── menu.pt.toml\n│   │       └── params.toml\n│   ├── content\n│   │   ├── _index.md\n```\n\nHowever, sometimes you may need to load additional style or script files. In such cases, you can add custom `.css` and `.js` files by listing them in the `config.toml` file (see the snippet below). Similar to images, these paths should be relative to the `static` directory.\n\n```yaml\n[params]\n...\ncustomCSS = [\"css/custom.css\"] # Include custom CSS files\ncustomJS = [\"js/custom.js\"] # Include custom JS files\n...\n```\n\n### Notices\n\nThis theme includes functionality to display some \"highlight blocks\" - called \"notices\" using a shortcode.\n\nFor example, see the shortcode markup below will render as a notice:\n\n```\n{{% notice note \"Note Title\" */%}}\nThis will be the content of the note.\n{{% /notice %}}\n```\n\nFor more examples see the \"Notices\" page in the `exampleSite`.\n\n### Site Disclaimer\n\n The theme includes the ability to put a Disclaimer on your website (e.g. \"My views are my own and not my employer's\").  Currently, the disclaimer displays in the sidebar under the author information.   You can enable and customize it as follows:\n\n * Uncomment the `sidebardisclaimer` parameter in `config/_default/params.toml`.\n * Uncomment and edit the `disclaimerText` parameter in `config/_default/params.toml`.\n * Add and modify an override for the `div.sidebardisclaimer` selector in `assets/saas/_custom.sass`.\n\n ```CSS\ndiv.sidebardisclaimer{padding: 0px 10px 15px 10px;margin: 20px 5px 20px 5px;border: 1px solid #eee;border-left-width: 10px;border-right-width: 10px;border-radius: 5px 5px 5px 5px;border-left-color: orange;border-right-color: orange;border-top-color:orange;border-bottom-color:orange}\n ```\n\n \u003e The code for the sidebar disclaimer text is in `layouts/partials/sidebar.html`.  The default color scheme displays in both light and dark mode.   Additionally, the styling has been placed into `_custom.sass` so that it's easily editable with beginner's understanding of CSS properties and easier to find.\n\n### Forcing light or dark mode\n\nBy default, sites authored using Clarity will load in the browser with the user's system-wide settings. I.e., if the underlying OS is set to dark mode, the site will automatically load in dark mode. Regardless of the default mode, a UI control switch exists to override the theme mode at the user's discretion.\n\nIn order to override this behavior and force one mode or another, add either `enforceLightMode` or `enforceDarkMode` to your `config.toml` file. If neither value is present, add it.\n\nTo enforce Light Mode by default, turn `enforceLightMode`  to `true`.\n\nTo enforce Dark Mode by default, turn `enforceDarkMode`  to `true`\n\n```yaml\n[params]\n...\nenforceLightMode = true # Force the site to always load in light mode.\n...\n```\n\nPlease note that you cannot enforce both modes at the same time. It wouldn't make sense, would it?\n\n\u003e ⚠️ Please also note that the mode toggle UI will remain in place. That way, if a user prefers dark mode, they can have their way. The best of both worlds.\n\n### I18N\n\nThis theme supports Multilingual (i18n / internationalization / translations)\n\nThe `exampleSite` gives you some examples already.\nYou may extend the multilingual functionality by following the [official documentation](https://gohugo.io/content-management/multilingual/).\n\nThings to consider in multilingual:\n\n* **supported languages** are configured in [config/_default/languages.toml](./exampleSite/config/_default/languages.toml)\n* **add new language support** by creating a new file inside [i18n](./i18n/) directory.\n  Check for missing translations using `hugo server --i18n-warnings`\n* **taxonomy** names (tags, categories, etc...) are translated in [i18n](./i18n/) as well (translate the key)\n* **menus** are translated manually in the config files [config/_default/menus/menu.xx.toml](./exampleSite/config/_default/menus/)\n* **menu's languages list** are semi-hardcoded. You may chose another text for the menu entry with [languageMenuName](./exampleSite/config/config.toml). Please, do better and create a PR for that.\n* **content** must be translated individually. Read the [official documentation](https://gohugo.io/content-management/multilingual/#translate-your-content) for information on how to do it.\n\n**note:** if you do NOT want any translations (thus removing the translations menu entry), then you must not have any translations.\nIn the exampleSite that's as easy as removing the extra translations from the `config/_default/...` or executing this one-liner:\n\n```sh\nsed '/^\\[pt]$/,$d' -i config/_default/languages.toml \u0026\u0026 rm config/_default/menus/menu.pt.toml\n```\n\nTo change the values of translatable text, such as `read_more` or `copyright`, edit the values in the language file you are using in the [`i18n`](i18n) directory. If you have no such directory, copy the one inside the theme to your root Hugo directory.\n\n### Hooks\n\nClarity provides some hooks for adding code on a page.\n\nIf you need to add some code (CSS import, HTML meta or similar) to the head section on every page, add a partial to your project:\n\n```\nlayouts/partials/hooks/head-end.html\n```\n\nSimilar, if you want to add some code right before the body end (e.g fonts' links), create your own version of the following file:\n\n```\nlayouts/partials/hooks/body-end.html\n```\n\n### Comments\n\nClarity supports Hugo built-in Disqus partial. You can enable Disqus simply by setting [`disqusShortname`](https://gohugo.io/templates/internal/#configure-disqus) in your [configuration file](https://github.com/chipzoller/hugo-clarity/blob/88f6cf4ac37c12990983b92d19842524555c23d3/exampleSite/config/config.toml#L11).\n\nYou can also override [layouts/partials/comments.html](https://github.com/chipzoller/hugo-clarity/blob/master/layouts/partials/comments.html) to take advantage of [disqus comments Alternatives](https://gohugo.io/content-management/comments/#comments-alternatives) for details.\n\n\u003e Please leave `#disqusShortname = \"\"` commented out if you decide to use other comments tools\n\nYou can disable them site-wide by setting `comments = false` under `[params]` from config.toml file and vice versa. Omitting that setting will default to comments will be enabled.\n\nYou can override these setting from each post individually. For example, you may want to disable/enable comments on specific posts. Use the same syntax used on the config.toml file.\n\n\u003e please use `comments` and not `comment`\n\n#### Utterances Commenting Support\n\nIf you wish use [Utterances](https://github.com/utterance/utterances) comments on your site, you'll need to perform the following:\n\n * Ensure you have a GitHub public repository, which you've granted permissions to the [Utterances GitHub App](https://github.com/apps/utterances).\n * Comment out the line for `disqusShortname = \"\"` in the `/config/_default/config.toml` file.\n * Set `comments = true` in the `/config/_default/params.toml` file.\n * Configure the utterances parameters in the `/config/_default/params.toml` file.\n * Optionally, you can choose a label that will be assigned to all issues created by Utterances. The label must exist in your Github repository, as Utterances cannot attach labels that do not exist. Configure `utterancesLabel` parameter in `/config/_default/params.toml` file, after you have added a label to your Github repository Issues labels. Labels are case sensitive and support Emoji in label names. ✨💬✨\n\nUtterances is loaded in the `comments.html` partial by referring to the `utterances.html` partial.   Since `single.html` layout loads comments if comments are enabled, you must ensure *both* the `comments` and `utterances` parameters are configured.\n\n#### Giscus Commenting Support\n\nIf you wish to use [giscus](https://giscus.app/) comments on your site, you'll need to perform the following:\n\n * Ensure your repository is [public](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/setting-repository-visibility#making-a-repository-public), otherwise visitors will not be able to view the discussion.\n * The [giscus app](https://github.com/apps/giscus) is installed, otherwise visitors will not be able to comment and react.\n * The Discussions feature is turned on by [enabling it for your repository](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/enabling-or-disabling-github-discussions-for-a-repository).\n * Comment out the line for `disqusShortname = \"\"` in the `/config/_default/config.toml` file.\n * Set `comments = true` in the `/config/_default/params.toml` file.\n * Configure the giscus parameters in the `/config/_default/params.toml` file.\n\nGiscus is loaded in the `comments.html` partial by referring to the `giscus.html` partial.   Since `single.html` layout loads comments if comments are enabled, you must ensure *both* the `comments` and `giscus` parameters are configured.\n\n\n### Math notation\n\nClarity uses [KaTeX](https://katex.org/) for math type setting if `enableMathNotation` is set to `true` in global or page parameters (the latter takes precedence).\n\nAlso see [supported TeX commands in KaTeX](https://katex.org/docs/supported.html).\n\nIf you want chemical typesetting provided by the [`mhchem`](https://mhchem.github.io/MathJax-mhchem/) extension, first copy `[site]/themes/clarity/layouts/partials/math.html` to `[site]/layouts/partials/math.html`:\n\n```bash\n# cd /path/to/site\nmkdir -p layouts/partials \u0026\u0026 cp themes/clarity/layouts/partials/math.html layouts/partials/math.html\n```\n\nThen add the corresponding line as its [README](https://github.com/KaTeX/KaTeX/tree/master/contrib/mhchem) suggested (without the `+` sign):\n\n```diff\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css\" integrity=\"sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X\" crossorigin=\"anonymous\"\u003e\n\n\u003cscript defer src=\"https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js\" integrity=\"sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n\n+ \u003cscript defer src=\"https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/mhchem.min.js\" integrity=\"sha384-ifpG+NlgMq0kvOSGqGQxW1mJKpjjMDmZdpKGq3tbvD3WPhyshCEEYClriK/wRVU0\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n\n\u003cscript defer src=\"https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js\" integrity=\"sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk\" crossorigin=\"anonymous\"\n  onload=\"renderMathInElement(document.body);\"\u003e\u003c/script\u003e\n```\n\nThe added line should be _before_ `auto-render.min.js` and _after_ `katex.min.js`.\n\n#### MathJax\n\nThe new version of MathJax has [comparable performance](https://www.intmath.com/cg5/katex-mathjax-comparison.php?processor=MathJax3) to KaTeX and better support for TeX commands.\n\nIf you prefer MathJax, create a blank `[site]/layouts/partials/math.html` and add the following two lines:\n\n```html\n\u003cscript src=\"https://polyfill.io/v3/polyfill.min.js?features=es6\"\u003e\u003c/script\u003e\n\u003cscript id=\"MathJax-script\" async src=\"https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js\"\u003e\u003c/script\u003e\n```\n\nThis file will [take precedence over](https://gohugobrasil.netlify.app/themes/customizing/) the one Clarity provides and the site will load MathJax instead of KaTeX.\n\n### Related Content\n\nRelated content within a `series` taxonomy can be shown at the end of a piece of content, or optionally on the sidebar above the Related Content section.\n\nThe site configuration option `showRelatedInArticle` controls if this option is enabled. The same configuration option can be used in a posts frontmatter to disable the feature (but the site configuration overrides the per-page option).\n\nLikewise, the site configuration option `showRelatedInSidebar` controls if related content is shown on the sidebar. There is no corresponding option within a post to disable this.\n\n### Maps\n\n#### Creating and including a map\n\nFirst create a map for free on https://umap.openstreetmap.fr/en/. Then include this map by using the `openstreetmap` shortcode, e.g. `{{\u003copenstreetmap mapName=\"demo-map_1\" \u003e}}`\n\n#### Options\n\nThe only required parameter is `mapName`. All other parameters are completely optional.\n\nAvailable parameters are:\n- `coordX` (default `auto`)\n- `coordY` (default `auto`)\n- `scale`  (default `auto`)\n- `scaleControl` (default `true`)\n- `miniMap` (default `false`)\n- `scrollWheelZoom` (default `true`)\n- `zoomControl` (default `true`)\n- `allowEdit` (default `false`)\n- `moreControl` (default `true`)\n- `searchControl` (default `true`)\n- `tilelayersControl` (default `null`)\n- `embedControl` (default `null`)\n- `datalayersControl` (default `true`)\n- `onLoadPanel` (default `none`)\n- `captionBar` (default `false`)\n\n### Search\n\nSearch is currently a BETA feature. Ensure you have these settings inside your configuration files:\n\n```toml\n# config/_default/config.toml\n[outputs]\n  home = [\"HTML\", \"RSS\",\"JSON\"]\n```\n\n```toml\n# config/_default/params.toml\nenableSearch = true\n```\n\nNext add the [search.md file from the exampleSite](https://raw.githubusercontent.com/chipzoller/hugo-clarity/master/exampleSite/content/search.md) and add it to your content folder. This is not necessary if you recently created a site based on the example site and already have the file.\n\n[Compose](https://github.com/onweru/compose), from which this feature is derived, implements `fuse.js` to enable search functionality. At the time of this writing, search on this theme takes either of the following forms:\n\n1. __Passive search__\n\n    This occurs only when the user loads the search page i.e `/search/`. They can directly navigate to that url. Alternatively, the user can type the search query on the search field and hit enter. They will be redirected to the search page which will contain matched results if any.\n\n    Currently, this only works on the default language. Support for multilingual passive search is coming soon.\n\n2. __Live search__\n\n    This behavior will be obvious as the user types a search query on the search field. All valid search queries will yield a list of quick links or a simple \"no matches found\". Else, the user will be prompted to continue typing.\n\n    Live search works even for multilingual sites.\n\n    For Chinese-like languages, it may or may not work.\n\n__Search Scope__\n\n- Searching within a section will yield results from that section.\n\n    For example, if you have 3 sections in your content i.e `blog`, `docs` \u0026 `examples`, searching in the `docs` section will only produce results for that section.\n- Searching outside a section will search the entire site.\n\n     For example, with the above setup, searching from the homepage will produce results from the entire site.\n\n### Basic Content Delivery Network (CDN) for Images and Files\n\nIf you intend to host images and files, you may decide you do not want to include them in your Git repository, as this can bloat the repository size.  If you create a basic CDN for your Hugo Site, this shortcode can assist with the embeds.  A basic CDN could be something like an S3 bucket, B2 bucket, B2 bucket behind Cloudflare transforms, etc.\n\nIn `params.toml`, configure the `[cdn]` section to include the following.  These are used by the \"cdn\" partial to generate the correct URLs for images and files:\n\n* `url` -- your base CDN url such as \"https://images.site.com/\" (including the trailing slash)\n* `imagesdir` = The url path for image files, such as \"images/\" (including the  trailing slash)\n* `filesdir` = The url path for downloadable files, such as \"files/\" (including the trailing slash)\n* `hotlinkdir` = The url path for images that can be hotlinked, such as \"images/hotlink-ok/\" (including the trailing slash)\n\nWith the params in place, you can use the shortcode as follows: `{{\u003c cdn [img|file|hlimg] [filename.extension] [alt name or link name] \u003e}}`\n* Example: `{{\u003c cdn \"img\" \"avatar.jpg\" \"My Avatar\" \u003e}}`\n* Example: `{{\u003c cdn \"file\" \"resume.pdf\" \"My Resume\" \u003e}}`\n* Example: `{{\u003c cdn \"hlimg\" \"hotlinkable-image.jpg\" \"My Image You Can Reference On Your Site\" \u003e}}`\n\n## Contributing\n\nPlease read our [contribution guidelines](CONTRIBUTING.md), and thank you for being involved!\n\n## Code of conduct\n\nHugo Clarity has a [code of conduct](CODE_OF_CONDUCT.md). Please follow it in all your interactions with the project.\n\n## License\n\nHugo Clarity is open-sourced under the [MIT license](https://github.com/chipzoller/hugo-clarity/blob/master/LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipzoller%2Fhugo-clarity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchipzoller%2Fhugo-clarity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipzoller%2Fhugo-clarity/lists"}