marcel
/
congo
mirror of https://github.com/jpanther/congo.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

📝 Update docs with v2 changes

pull/100/head
James Panther 2022-01-24 16:51:28 +11:00
parent b59137e458
commit 3703a09ce3
No known key found for this signature in database
GPG Key ID: D36F789E45745D17
10 changed files with 305 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
config/_default/params.toml
View File

@ -20,6 +20,7 @@ showScrollToTop = true
[article] [article]
showDate = true showDate = true
showDateUpdated = false
showAuthor = true showAuthor = true
showBreadcrumbs = false showBreadcrumbs = false
showDraftLabel = true showDraftLabel = true
@ -29,8 +30,8 @@ showScrollToTop = true
showHeadingAnchors = true showHeadingAnchors = true
showPagination = true showPagination = true
showReadingTime = true showReadingTime = true
showTaxonomies = false
showTableOfContents = false showTableOfContents = false
showTaxonomies = false
showWordCount = false showWordCount = false
# sharingLinks = ["facebook", "twitter", "pinterest", "reddit", "linkedin", "email"] # sharingLinks = ["facebook", "twitter", "pinterest", "reddit", "linkedin", "email"]
@ -40,12 +41,12 @@ showScrollToTop = true
showTableOfContents = false showTableOfContents = false
groupByYear = true groupByYear = true
[taxonomy]
showTermCount = true
[sitemap] [sitemap]
excludedKinds = ["taxonomy", "term"] excludedKinds = ["taxonomy", "term"]
[taxonomy]
showTermCount = true
[fathomAnalytics] [fathomAnalytics]
# site = "ABC12345" # site = "ABC12345"
# domain = "llama.yoursite.com" # domain = "llama.yoursite.com"

9
exampleSite/config/_default/params.toml
View File

@ -20,6 +20,7 @@ showScrollToTop = true
[article] [article]
showDate = true showDate = true
showDateUpdated = false
showAuthor = true showAuthor = true
showBreadcrumbs = true showBreadcrumbs = true
showDraftLabel = true showDraftLabel = true
@ -29,8 +30,8 @@ showScrollToTop = true
showHeadingAnchors = true showHeadingAnchors = true
showPagination = true showPagination = true
showReadingTime = true showReadingTime = true
showTaxonomies = false
showTableOfContents = true showTableOfContents = true
showTaxonomies = false
showWordCount = false showWordCount = false
# sharingLinks = ["facebook", "twitter", "pinterest", "reddit", "linkedin", "email"] # sharingLinks = ["facebook", "twitter", "pinterest", "reddit", "linkedin", "email"]
@ -40,12 +41,12 @@ showScrollToTop = true
showTableOfContents = true showTableOfContents = true
groupByYear = false groupByYear = false
[taxonomy]
showTermCount = true
[sitemap] [sitemap]
excludedKinds = ["taxonomy", "term"] excludedKinds = ["taxonomy", "term"]
[taxonomy]
showTermCount = true
[fathomAnalytics] [fathomAnalytics]
# site = "ABC12345" # site = "ABC12345"
# domain = "llama.yoursite.com" # domain = "llama.yoursite.com"

110
exampleSite/content/docs/advanced-customisation.md
View File

@ -60,36 +60,112 @@ html {
Simply by changing this one value, all the font sizes on your website will be adjusted to match this new size. Therefore, to increase the overall font sizes used, make the value greater than `12pt`. Similarly, to decrease the font sizes, make the value less than `12pt`. Simply by changing this one value, all the font sizes on your website will be adjusted to match this new size. Therefore, to increase the overall font sizes used, make the value greater than `12pt`. Similarly, to decrease the font sizes, make the value less than `12pt`.
## Building from source ## Building the Tailwind CSS from source
If you'd like to make a major change, you can take advantage of Tailwind CSS's JIT compiler and rebuild the entire theme CSS from scratch. If you'd like to make a major change, you can take advantage of Tailwind CSS's JIT compiler and rebuild the entire theme CSS from scratch. This is useful if you want to adjust the Tailwind configuration or add extra Tailwind classes to the main stylesheet.
{{< alert >}} {{< alert >}}
**Note:** Building the theme manually is intended for advanced users. **Note:** Building the theme manually is intended for advanced users.
{{< /alert >}} {{< /alert >}}
Change into the `themes/congo/` folder and install the project dependencies. Let's step through how building the Tailwind CSS works.
```bash ### Tailwind configuration
In order to generate a CSS file that only contains the Tailwind classes that are actually being used the JIT compiler needs to scan through all the HTML templates and Markdown content files to check which styles are present in the markup. The compiler does this by looking at the `tailwind.config.js` file which is included in the root of the theme directory:
```js
// themes/congo/tailwind.config.js
module.exports = {
content: [
"./layouts/**/*.html",
"./content/**/*.{html,md}",
"./themes/congo/layouts/**/*.html",
"./themes/congo/content/**/*.{html,md}",
],
// and more...
};
```
This default configuration has been included with these content paths so that you can easily generate your own CSS file without needing to modify it, provided you follow a particular project structure. Namely, **you have to include Congo in your project as a subdirectory at `themes/congo/`**. This means you cannot easily use Hugo Modules to install the theme and you must go down either the git submodule (recommended) or manual install routes. The [Installation docs]({{< ref "installation" >}}) explain how to install the theme using either of these methods.
### Project structure
In order to take advantage of the default configuration, your project should look something like this...
```shell
.
├── assets
│ └── css
│ └── compiled
│ └── main.css # this is the file we will generate
├── config # site config
│ └── _default
├── content # site content
│ ├── _index.md
│ ├── projects
│ │ └── _index.md
│ └── blog
│ └── _index.md
├── layouts # custom layouts for your site
│ ├── partials
│ │ └── extend-article-link.html
│ ├── projects
│ │ └── list.html
│ └── shortcodes
│ └── disclaimer.html
└── themes
└── congo # git submodule or manual theme install
```
This example structure adds a new `projects` content type with its own custom layout along with a custom shortcode and extended partial. Provided the project follows this structure, all that's required is to recompile the `main.css` file.
### Install dependencies
In order for this to work you'll need to change into the `themes/congo/` directory and install the project dependencies. You'll need [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) on your local machine for this step.
```shell
cd themes/congo
npm install npm install
``` ```
Once installed, you can edit the `themes/congo/tailwind.config.js` to change the styles that are applied throughout the theme. You can also adjust specific styles in `themes/congo/assets/css/main.css`. ### Run the Tailwind compiler
To allow for easy theme colour changes, Congo defines a three-colour palette that is used throughout the theme. The three colours are defined as `neutral`, `primary` and `secondary` variants, each containing ten shades of colour. In order to change the colour across the entire theme, simply edit the `tailwind.config.js` file accordingly. With the dependencies installed all that's left is to use [Tailwind CLI](https://v2.tailwindcss.com/docs/installation#using-tailwind-cli) to invoke the JIT compiler. Navigate back to the root of your Hugo project and issue the following command:
For a full list of colours available, and their corresponding configuration values, see the official [Tailwind docs](https://tailwindcss.com/docs/customizing-colors#color-palette-reference). ```shell
cd ../..
After editing the configuration, you need to rebuild the theme's stylesheets. This will run the Tailwind JIT compiler in watch mode which aids with testing style changes. ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit
```bash
npm run dev
``` ```
This will automatically output a CSS file to `/themes/congo/assets/css/compiled/main.css`. It's a bit of an ugly command due to the paths involved but essentially you're calling Tailwind CLI and passing it the location of the Tailwind config file (the one we looked at above), where to find the theme's `main.css` file and then where you want the compiled CSS file to be placed (it's going into the `assets/css/compiled/` folder of your Hugo project).
{{< alert >}} The config file will automatically inspect all the content and layouts in your project as well as all those in the theme and build a new CSS file that contains all the CSS required for your website. Due to the way Hugo handles file hierarchy, this file in your project will now automatically override the one that comes with the theme.
**Note:** You should not make manual edits to the compiled CSS file.
{{< /alert >}}
Now whenever you make a change, the CSS files will be rebuilt automatically. This mode is useful to run when using `hugo server` to preview your site during development. Asset files will be minified by Hugo at site build time. Each time you make a change to your layouts and need new Tailwind CSS styles, you can simply re-run the command and generate the new CSS file. You can also add `-w` to the end of the command to run the JIT compiler in watch mode.
### Make a build script
To fully complete this solution, you can simplify this whole process by adding aliases for these commands, or do what I do and add a `package.json` to the root of your project which contains the necessary scripts...
```js
// package.json
{
"name": "my-website",
"version": "1.0.0",
"description": "",
"scripts": {
"server": "hugo server -b http://localhost -p 8000",
"dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
"build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
},
// and more...
}
```
Now when you want to work on designing your site, you can invoke `npm run dev` and the compiler will run in watch mode. When you're ready to deploy, run `npm run build` and you'll get a clean Tailwind CSS build.
🙋‍♀️ If you need help, feel free to ask a question on [GitHub Discussions](https://github.com/jpanther/congo/discussions).

151
exampleSite/content/docs/configuration.md
View File

@ -25,25 +25,67 @@ Standard Hugo configuration variables are respected throughout the theme, howeve
The site configuration is managed through the `config/_default/config.toml` file. The table below outlines all the settings that the Congo takes advantage of. The site configuration is managed through the `config/_default/config.toml` file. The table below outlines all the settings that the Congo takes advantage of.
Note that the variable names provided in this table use dot notation to simplify the TOML data structure (ie. `author.name` refers to `[author] name`). Note that the variable names provided in this table use dot notation to simplify the TOML data structure (ie. `outputs.home` refers to `[outputs] home`).
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
|Name|Type|Default|Description| |Name|Default|Description|
| --- | --- | --- | --- | |---|---|---|
|`theme`|string|`"congo"`|When using Hugo Modules this config value should be removed. For all other installation types, this must be set to `congo` for the theme to function.| |`theme`|`"congo"`|When using Hugo Modules this config value should be removed. For all other installation types, this must be set to `congo` for the theme to function.|
|`baseURL`|string|_Not set_|The URL to the root of the website.| |`baseURL`|_Not set_|The URL to the root of the website.|
|`languageCode`|string|`"en"`|The language of the website for site metadata purposes. It can be a top-level language (ie. `en`) or a sub-variant (ie. `en-AU`)."| |`defaultContentLanguage`|`"en"`|This value determines the default language of theme components and content. Refer to the [language and i18n](#language-and-i18n) section below for supported language codes.|
|`defaultContentLanguage`|string|`"en"`|This value determines the language of theme components."| |`enableRobotsTXT`|`true`|When enabled a `robots.txt` file will be created in the site root that allows search engines to crawl the entire site. Set to `false` if you wish to provide your own file.|
|`title`|string|`"Congo"`|The title of the website. This will be displayed in the site header and footer.| |`summaryLength`|`0`|The number of words that are used to generate the article summary when one is not provided in the [front matter]({{< ref "front-matter" >}}). A value of `0` will use the first sentence. This value has no effect when summaries are hidden.|
|`copyright`|string|_Not set_|A Markdown string containing the copyright message to be displayed in the site footer. If none is provided, Congo will automatically generate a copyright string using the site `title`. |`outputs.home`|`["HTML", "RSS", "JSON"]`|The output formats that are generated for the site. Congo requires HTML, RSS and JSON for all theme components to work correctly.|
|`enableRobotsTXT`|boolean|`true`|When enabled a `robots.txt` file will be created in the site root that allows search engines to crawl the entire site. Set to `false` if you wish to provide your own file.| |`permalinks`|_Not set_|Refer to the [Hugo docs](https://gohugo.io/content-management/urls/#permalinks) for permalink configuration.|
|`summaryLength`|integer|`0`|The number of words that are used to generate the article summary when one is not provided in the [front matter]({{< ref "front-matter" >}}). A value of `0` will use the first sentence. This value has no effect when summaries are hidden.| |`taxonomies`|_Not set_|Refer to the [Organising content]({{< ref "getting-started#organising-content" >}}) section for taxonomy configuration.|
|`author.name`|string|_Not set_|The author's name. This will be displayed in article footers, and on the homepage when the profile layout is used.| <!-- prettier-ignore-end -->
|`author.image`|string|_Not set_|Path to the image file of the author. The image should be a 1:1 aspect ratio and placed in the site's `static/` folder.|
|`author.bio`|string|_Not set_|A Markdown string containing the author's bio. It will be displayed in article footers.| ## Language and i18n
|`author.links`|array of objects|_Not set_|The links to display alongside the author's details. The config file contains example links which can simply be uncommented to enable. The order that the links are displayed is determined by the order they appear in the array. Custom links can be added by providing corresponding SVG icon assets in `assets/icons/`.|
|`permalinks`||_Not set_|Refer to the [Hugo docs](https://gohugo.io/content-management/urls/#permalinks) for permalink configuration.| Congo is optimised for full multilingual websites and theme assets are translated into several languages out of the box. The language configuration allows you to generate multiple versions of your content to provide a customised experience to your visitors in their native language.
|`taxonomies`||_Not set_|Refer to the [Organising content]({{< ref "getting-started#organising-content" >}}) section for taxonomy configuration.|
The theme currently supports the following languages by default:
| Language | Code |
| ---------------------------- | ------- |
| :gb: English | `en` |
| :cn: Chinese | `zh` |
| :fr: French | `fr` |
| :de: German | `de` |
| :brazil: Portuguese (Brazil) | `pt-br` |
| :es: Spanish (Spain) | `es` |
| :tr: Turkish | `tr` |
The default translations can be overridden by creating a custom file in `i18n/[code].yaml` that contains the translation strings. You can also use this method to add new languages. If you'd like to share a new translation with the community, please [open a pull request](https://github.com/jpanther/congo/pulls).
### Configuration
In order to be as flexible as possible, a language configuration file needs to be created for each language on the website. By default Congo includes an English language configuration at `config/_default/languages.en.toml`.
The default file can be used as a template to create additional languages, or renamed if you wish to author your website in a language other than English. Simply name the file using the format `languages.[language-code].toml`.
{{< alert >}}
**Note:** Ensure the `defaultContentLanguage` parameter in the [site configuration](#site-configuration) matches the language code in your language config filename.
{{< /alert >}}
<!-- prettier-ignore-start -->
|Name|Default|Description|
|---|---|---|
|`languageCode`|`"en"`|The language code for this file. It can be a top-level language (ie. `en`) or a sub-variant (ie. `en-au`) and should match the language code in the filename. Hugo expects this value to always be in lowercase. For proper HTML compliance, set the `htmlCode` parameter which is case-sensitive.|
|`languageName`|`"English"`|The name of the language.|
|`displayName`|`"EN"`|The name used when the language appears on the website.|
|`htmlCode`|`"en"`|The language code for HTML metadata purposes. It can be a top-level language (ie. `en`) or a sub-variant (ie. `en-AU`).|
|`weight`|`1`|The weight determines the order of languages when building multilingual sites.|
|`rtl`|`false`|Whether or not this is a RTL language. Set to `true` to reflow content from right-to-left. Congo fully supports using RTL and LTR languages at the same time and will dynamically adjust to both.|
|`dateFormat`|`"2 January 2006"`|How dates are formatted in this language. Refer to the [Hugo docs](https://gohugo.io/functions/format/#gos-layout-string) for acceptable formats.|
|`title`|`"Congo"`|The title of the website. This will be displayed in the site header and footer.|
|`description`|_Not set_|The website description. This will be used in the site metadata.|
|`copyright`|_Not set_|A Markdown string containing the copyright message to be displayed in the site footer. If none is provided, Congo will automatically generate a copyright string using the site `title`.|
|`author.name`|_Not set_|The author's name. This will be displayed in article footers, and on the homepage when the profile layout is used.|
|`author.image`|_Not set_|Path to the image file of the author. The image should be a 1:1 aspect ratio and placed in the site's `assets/` folder.|
|`author.headline`|_Not set_|A Markdown string containing the author's headline. It will be displayed on the profile homepage under the author's name.|
|`author.bio`|_Not set_|A Markdown string containing the author's bio. It will be displayed in article footers.|
|`author.links`|_Not set_|The links to display alongside the author's details. The config file contains example links which can simply be uncommented to enable. The order that the links are displayed is determined by the order they appear in the array. Custom links can be added by providing corresponding SVG icon assets in `assets/icons/`.|
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
## Theme parameters ## Theme parameters
@ -53,40 +95,43 @@ Congo provides a large number of configuration parameters that control how the t
Many of the article defaults here can be overridden on a per article basis by specifying it in the front matter. Refer to the [Front Matter]({{< ref "front-matter" >}}) section for further details. Many of the article defaults here can be overridden on a per article basis by specifying it in the front matter. Refer to the [Front Matter]({{< ref "front-matter" >}}) section for further details.
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
|Name|Type|Default|Description| |Name|Default|Description|
| --- | --- | --- | --- | |---|---|---|
|`colorScheme`|string|`"congo"`|The theme colour scheme to use. Valid values are `congo` (default), `avocado`, `ocean`, `fire` and `slate`. Refer to the [Colour Schemes]({{< ref "getting-started#colour-schemes" >}}) section for more details.| |`colorScheme`|`"congo"`|The theme colour scheme to use. Valid values are `congo` (default), `avocado`, `ocean`, `fire` and `slate`. Refer to the [Colour Schemes]({{< ref "getting-started#colour-schemes" >}}) section for more details.|
|`darkMode`|boolean or string|`"auto"`|The preferred theme appearance for dark mode. Set to `true` to force dark appearance or `false` to force light appearance. Using `"auto"` will defer to the user's operating system preference.| |`enableSearch`|`false`|Whether site search is enabled. Set to `true` to enable search functionality. Note that the search feature depends on the `outputs.home` setting in the [site configuration](#site-configuration) being set correctly.|
|`darkToggle`|boolean|`false`|When `darkMode` is set to `"auto"`, this parameter determines whether or not to show the appearance toggle in the site footer. The browser's local storage is used to persist the user's preference.| |`darkMode`|`"auto"`|The preferred theme appearance for dark mode. Set to `true` to force dark appearance or `false` to force light appearance. Using `"auto"` will defer to the user's operating system preference.|
|`logo`|string|_Not set_|The relative path to the site logo file within the `assets/` folder. The logo file should be provided at 2x resolution and supports any image dimensions.| |`logo`|_Not set_|The relative path to the site logo file within the `assets/` folder. The logo file should be provided at 2x resolution and supports any image dimensions.|
|`description`|string|_Not set_|The description of the website for metadata purposes.| |`mainSections`|_Not set_|The sections that should be displayed in the recent articles list. If not provided the section with the greatest number of articles is used.|
|`mainSections`|array of strings|_Not set_|The sections that should be displayed in the recent articles list. If not provided the section with the greatest number of articles is used.| |`robots`|_Not set_|String that indicates how robots should handle your site. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.|
|`robots`|string|_Not set_|String that indicates how robots should handle your site. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.| |`showDarkToggle`|`false`|When `darkMode` is set to `"auto"`, this parameter determines whether or not to show the appearance toggle in the site footer. The browser's local storage is used to persist the user's preference.|
|`homepage.layout`|string|`"page"`|The layout of the homepage. Valid values are `page`, `profile` or `custom`. When set to `custom`, you must provide your own layout by creating a `/layouts/partials/home/custom.html` file. Refer to the [Homepage Layout]({{< ref "homepage-layout" >}}) section for more details.| |`showScrollToTop`|`true`|When set to `true` the scroll to top arrow is displayed.|
|`homepage.showRecent`|boolean|`false`|Whether or not to display the recent articles list on the homepage.| |`homepage.layout`|`"page"`|The layout of the homepage. Valid values are `page`, `profile` or `custom`. When set to `custom`, you must provide your own layout by creating a `/layouts/partials/home/custom.html` file. Refer to the [Homepage Layout]({{< ref "homepage-layout" >}}) section for more details.|
|`article.showDate`|boolean|`true`|Whether or not article dates are displayed.| |`homepage.showRecent`|`false`|Whether or not to display the recent articles list on the homepage.|
|`article.showDateUpdated`|boolean|`false`|Whether or not the dates articles were updated are displayed.| |`article.showDate`|`true`|Whether or not article dates are displayed.|
|`article.dateFormat`|string|`"2 January 2006"`|How article dates are formatted. Refer to the [Hugo docs](https://gohugo.io/functions/format/#gos-layout-string) for acceptable formats.| |`article.showDateUpdated`|`false`|Whether or not the dates articles were updated are displayed.|
|`article.showAuthor`|boolean|`true`|Whether or not the author box is displayed in the article footer.| |`article.showAuthor`|`true`|Whether or not the author box is displayed in the article footer.|
|`article.showBreadcrumbs`|boolean|`false`|Whether or not breadcrumbs are displayed in the article header.| |`article.showBreadcrumbs`|`false`|Whether or not breadcrumbs are displayed in the article header.|
|`article.showDraftLabel`|boolean|`true`|Whether or not the draft indicator is shown next to articles when site is built with `--buildDrafts`.| |`article.showDraftLabel`|`true`|Whether or not the draft indicator is shown next to articles when site is built with `--buildDrafts`.|
|`article.showEdit`|boolean|`false`|Whether or not the link to edit the article content should be displayed.| |`article.showEdit`|`false`|Whether or not the link to edit the article content should be displayed.|
|`article.editURL`|string|_Not set_|When `article.showEdit` is active, the URL for the edit link.| |`article.editURL`|_Not set_|When `article.showEdit` is active, the URL for the edit link.|
|`article.editAppendPath`|boolean|`true`|When `article.showEdit` is active, whether or not the path to the current article should be appended to the URL set at `article.editURL`.| |`article.editAppendPath`|`true`|When `article.showEdit` is active, whether or not the path to the current article should be appended to the URL set at `article.editURL`.|
|`article.showHeadingAnchors`|boolean|`true`|Whether or not heading anchor links are displayed alongside headings within articles.| |`article.showHeadingAnchors`|`true`|Whether or not heading anchor links are displayed alongside headings within articles.|
|`article.showPagination`|boolean|`true`|Whether or not the next/previous article links are displayed in the article footer.| |`article.showPagination`|`true`|Whether or not the next/previous article links are displayed in the article footer.|
|`article.showReadingTime`|boolean|`true`|Whether or not article reading times are displayed.| |`article.showReadingTime`|`true`|Whether or not article reading times are displayed.|
|`article.showWordCount`|boolean|`false`|Whether or not article word counts are displayed.| |`article.showTableOfContents`|`false`|Whether or not the table of contents is displayed on articles.|
|`article.sharingLinks`|array of strings|_Not set_|Which sharing links to display at the end of each article. When not provided, or set to `false` no links will be displayed.| |`article.showTaxonomies`|`false`|Whether or not the taxonomies related to this article are displayed.|
|`list.showBreadcrumbs`|boolean|`false`|Whether or not breadcrumbs are displayed in the header on list pages.| |`article.showWordCount`|`false`|Whether or not article word counts are displayed.|
|`list.showSummary`|boolean|`false`|Whether or not article summaries are displayed on list pages. If a summary is not provided in the [front matter]({{< ref "front-matter" >}}), one will be auto generated using the `summaryLength` parameter in the [site configuration](#site-configuration).| |`article.sharingLinks`|_Not set_|Which sharing links to display at the end of each article. When not provided, or set to `false` no links will be displayed.|
|`list.groupByYear`|boolean|`true`|Whether or not articles are grouped by year on list pages.| |`list.showBreadcrumbs`|`false`|Whether or not breadcrumbs are displayed in the header on list pages.|
|`sitemap.excludedKinds`|array of strings|`["taxonomy", "term"]`|Kinds of content that should be excluded from the generated `/sitemap.xml` file. Refer to the [Hugo docs](https://gohugo.io/templates/section-templates/#page-kinds) for acceptable values.| |`list.showTableOfContents`|`false`|Whether or not the table of contents is displayed on list pages.|
|`taxonomy.showTermCount`|boolean|`true`|Whether or not the number of articles within a taxonomy term is displayed on the taxonomy listing.| |`list.showSummary`|`false`|Whether or not article summaries are displayed on list pages. If a summary is not provided in the [front matter]({{< ref "front-matter" >}}), one will be auto generated using the `summaryLength` parameter in the [site configuration](#site-configuration).|
|`fathomAnalytics.site`|string|_Not set_|The site code generated by Fathom Analytics for the website. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.| |`list.groupByYear`|`true`|Whether or not articles are grouped by year on list pages.|
|`fathomAnalytics.domain`|string|_Not set_|If using a custom domain with Fathom Analytics, provide it here to serve `script.js` from the custom domain.| |`sitemap.excludedKinds`|`["taxonomy", "term"]`|Kinds of content that should be excluded from the generated `/sitemap.xml` file. Refer to the [Hugo docs](https://gohugo.io/templates/section-templates/#page-kinds) for acceptable values.|
|`verification.google`|string|_Not set_|The site verification string provided by Google to be included in the site metadata.| |`taxonomy.showTermCount`|`true`|Whether or not the number of articles within a taxonomy term is displayed on the taxonomy listing.|
|`verification.bing`|string|_Not set_|The site verification string provided by Bing to be included in the site metadata.| |`fathomAnalytics.site`|_Not set_|The site code generated by Fathom Analytics for the website. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.|
|`verification.pinterest`|string|_Not set_|The site verification string provided by Pinterest to be included in the site metadata.| |`fathomAnalytics.domain`|_Not set_|If using a custom domain with Fathom Analytics, provide it here to serve `script.js` from the custom domain.|
|`verification.yandex`|string|_Not set_|The site verification string provided by Yandex to be included in the site metadata.| |`verification.google`|_Not set_|The site verification string provided by Google to be included in the site metadata.|
|`verification.bing`|_Not set_|The site verification string provided by Bing to be included in the site metadata.|
|`verification.pinterest`|_Not set_|The site verification string provided by Pinterest to be included in the site metadata.|
|`verification.yandex`|_Not set_|The site verification string provided by Yandex to be included in the site metadata.|
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->

45
exampleSite/content/docs/front-matter.md
View File

@ -12,25 +12,28 @@ In addition to the [default Hugo front matter parameters](https://gohugo.io/cont
Front matter parameter default values are inherited from the theme's [base configuration]({{< ref "configuration" >}}), so you only need to specify these parameters in your front matter when you want to override the default. Front matter parameter default values are inherited from the theme's [base configuration]({{< ref "configuration" >}}), so you only need to specify these parameters in your front matter when you want to override the default.
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
|Name|Type|Default|Description| |Name|Default|Description|
| --- | --- | --- | --- | |---|---|---|
|`description`|string|_Not set_|The text description for the article. It is used in the HTML metadata.| |`title`|_Not set_|The name of the article.|
|`externalUrl`|string|_Not set_|If this article is published on a third-party website, the URL to this article. Providing a URL will prevent a content page being generated and any references to this article will link directly to the third-party website.| |`description`|_Not set_|The text description for the article. It is used in the HTML metadata.|
|`editURL`|string|`article.editURL`|When `showEdit` is active, the URL for the edit link.| |`externalUrl`|_Not set_|If this article is published on a third-party website, the URL to this article. Providing a URL will prevent a content page being generated and any references to this article will link directly to the third-party website.|
|`editAppendPath`|boolean|`article.editAppendPath`|When `showEdit` is active, whether or not the path to the current article should be appended to the URL set at `editURL`.| |`editURL`|`article.editURL`|When `showEdit` is active, the URL for the edit link.|
|`groupByYear`|boolean|`list.groupByYear`|Whether or not articles are grouped by year on list pages.| |`editAppendPath`|`article.editAppendPath`|When `showEdit` is active, whether or not the path to the current article should be appended to the URL set at `editURL`.|
|`menu`|string or array|_Not set_|When a value is provided, a link to this article will appear in the named menus. Valid values are `main` or `footer`.| |`groupByYear`|`list.groupByYear`|Whether or not articles are grouped by year on list pages.|
|`robots`|string|_Not set_|String that indicates how robots should handle this article. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.| |`menu`|_Not set_|When a value is provided, a link to this article will appear in the named menus. Valid values are `main` or `footer`.|
|`sharingLinks`|array of strings|`article.sharingLinks`|Which sharing links to display at the end of this article. When not provided, or set to `false` no links will be displayed.| |`robots`|_Not set_|String that indicates how robots should handle this article. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.|
|`showAuthor`|boolean|`article.showAuthor`|Whether or not the author box is displayed in the article footer.| |`sharingLinks`|`article.sharingLinks`|Which sharing links to display at the end of this article. When not provided, or set to `false` no links will be displayed.|
|`showDate`|boolean|`article.showDate`|Whether or not the article date is displayed. The date is set using the `date` parameter.| |`showAuthor`|`article.showAuthor`|Whether or not the author box is displayed in the article footer.|
|`showDateUpdated`|boolean|`article.showDateUpdated`|Whether or not the date the article was updated is displayed. The date is set using the `lastmod` parameter.| |`showDate`|`article.showDate`|Whether or not the article date is displayed. The date is set using the `date` parameter.|
|`showEdit`|boolean|`article.showEdit`|Whether or not the link to edit the article content should be displayed.| |`showDateUpdated`|`article.showDateUpdated`|Whether or not the date the article was updated is displayed. The date is set using the `lastmod` parameter.|
|`showHeadingAnchors`|boolean|`article.showHeadingAnchors`|Whether or not heading anchor links are displayed alongside headings within this article.| |`showEdit`|`article.showEdit`|Whether or not the link to edit the article content should be displayed.|
|`showPagination`|boolean|`article.showPagination`|Whether or not the next/previous article links are displayed in the article footer.| |`showHeadingAnchors`|`article.showHeadingAnchors`|Whether or not heading anchor links are displayed alongside headings within this article.|
|`showReadingTime`|boolean|`article.showReadingTime`|Whether or not the article reading time is displayed.| |`showPagination`|`article.showPagination`|Whether or not the next/previous article links are displayed in the article footer.|
|`showWordCount`|boolean|`article.showWordCount`|Whether or not the article word count is displayed.| |`showReadingTime`|`article.showReadingTime`|Whether or not the article reading time is displayed.|
|`showSummary`|boolean|`list.showSummary`|Whether or not the article summary should be displayed on list pages.| |`showTaxonomies`|`article.showTaxonomies`|Whether or not the taxonomies that relate to this article are displayed.|
|`summary`|string|Auto generated using `summaryLength` (see [site configuration]({{< ref "configuration#site-configuration" >}}))|When `showSummary` is enabled, this is the Markdown string to be used as the summary for this article.| |`showTableOfContents`|`article.showTableOfContents`|Whether or not the table of contents is displayed on this article.|
|`xml`|boolean|`true` unless excluded by `sitemap.excludedKinds`|Whether or not this article is included in the generated `/sitemap.xml` file.| |`showWordCount`|`article.showWordCount`|Whether or not the article word count is displayed.|
|`showSummary`|`list.showSummary`|Whether or not the article summary should be displayed on list pages.|
|`summary`|Auto generated using `summaryLength` (see [site configuration]({{< ref "configuration#site-configuration" >}}))|When `showSummary` is enabled, this is the Markdown string to be used as the summary for this article.|
|`xml`|`true` unless excluded by `sitemap.excludedKinds`|Whether or not this article is included in the generated `/sitemap.xml` file.|
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->

54
exampleSite/content/docs/getting-started.md
View File

@ -13,27 +13,43 @@ This section assumes you have already [installed the Congo theme]({{< ref "docs/
The config files that ship with Congo contain all of the possible settings that the theme recognises. By default, many of these are commented out but you can simply uncomment them to activate or change a specific feature. The config files that ship with Congo contain all of the possible settings that the theme recognises. By default, many of these are commented out but you can simply uncomment them to activate or change a specific feature.
There are a few things you should set in `config.toml` for a new installation: ## Basic configuration
Before creating any content, there are a few things you should set for a new installation. Starting in the `config.toml` file, set the `baseURL` and `languageCode` parameters. The `languageCode` should be set to the main language that you will be using to author your content.
```toml ```toml
# config/_default/config.toml # config/_default/config.toml
baseURL = "https://your_domain.com" baseURL = "https://your_domain.com"
languageCode = "en-AU" languageCode = "en"
```
The next step is to configure the language settings. Although Congo supports multilingual setups, for now, just configure the main language.
Locate the `languages.en.toml` file in the config folder. If your main language is English you can use this file as is. Otherwise, rename it so that it includes the correct language code in the filename. For example, for French, rename the file to `languages.fr.toml`.
{{< alert >}}
Note that the language code in the language config filename should match the `languageCode` setting in `config.toml`.
{{< /alert >}}
```toml
# config/_default/languages.en.toml
title = "My awesome website" title = "My awesome website"
[author] [author]
name = "My name" name = "My name"
image = "img/author.jpg" image = "img/author.jpg"
headline = "A generally awesome human"
bio = "A little bit about me" bio = "A little bit about me"
links = [ links = [
{ twitter = "https://twitter.com/username" } { twitter = "https://twitter.com/username" }
] ]
``` ```
The `[author]` configuration determines how the author information is displayed on the website. The image should be placed in the site's `static/` folder. Links will be displayed in the order they are listed. The `[author]` configuration determines how the author information is displayed on the website. The image should be placed in the site's `assets/` folder. Links will be displayed in the order they are listed.
Further detail about these configuration options is covered in the [Configuration]({{< ref "configuration" >}}) section. If you need extra detail, further information about each of these configuration options, is covered in the [Configuration]({{< ref "configuration" >}}) section.
## Colour schemes ## Colour schemes
@ -73,9 +89,33 @@ Although these are the default schemes, you can also create your own. Refer to t
By default, Congo doesn't force you to use a particular content type. In doing so you are free to define your content as you wish. You might prefer _pages_ for a static site, _posts_ for a blog, or _projects_ for a portfolio. By default, Congo doesn't force you to use a particular content type. In doing so you are free to define your content as you wish. You might prefer _pages_ for a static site, _posts_ for a blog, or _projects_ for a portfolio.
The same logic applies to taxonomies. Some people prefer to use _tags_ and _categories_, others prefer to use _topics_. Here's a quick overview of a basic Congo project. All content is placed within the `content` folder:
Hugo defaults to using posts, tags and categories out of the box and this will work fine if that's what you want. If you wish to customise this, however, you can do so by creating the following files: ```shell
.
├── assets
│ └── img
│ └── author.jpg
├── config
│ └── _default
├── content
│ ├── _index.md
│ ├── about.md
│ └── posts
│ ├── _index.md
│ ├── first-post.md
│ └── another-post
│ ├── aardvark.jpg
│ └── index.md
└── themes
└── congo
```
It's important to have a firm grasp of how Hugo expects content to be organised as the theme is designed to take full advantage of Hugo page bundles. Be sure to read the [official Hugo docs](https://gohugo.io/content-management/organization/) for more information.
Congo is also flexible when it comes to taxonomies. Some people prefer to use _tags_ and _categories_ to group their content, others prefer to use _topics_.
Hugo defaults to using posts, tags and categories out of the box and this will work fine if that's what you want. If you wish to customise this, however, you can do so by creating a `taxonomies.toml` configuation file:
```toml ```toml
# config/_default/taxonomies.toml # config/_default/taxonomies.toml
@ -85,7 +125,7 @@ topic = "topics"
This will replace the default _tags_ and _categories_ with _topics_. Refer to the [Hugo Taxonomy docs](https://gohugo.io/content-management/taxonomies/) for more information on naming taxonomies. This will replace the default _tags_ and _categories_ with _topics_. Refer to the [Hugo Taxonomy docs](https://gohugo.io/content-management/taxonomies/) for more information on naming taxonomies.
When you create a new taxonomy, you will need to adjust the navigation links on the website to point to the correct sections. When you create a new taxonomy, you will need to adjust the navigation links on the website to point to the correct sections, which is covered below.
## Menus ## Menus

2
exampleSite/content/docs/homepage-layout/index.md
View File

@ -25,7 +25,7 @@ The profile layout is great for personal websites and blogs. It puts the author'
![Screenshot of profile layout](home-profile.jpg) ![Screenshot of profile layout](home-profile.jpg)
The author information is provided in the `config.toml` configuration file. Refer to the [Getting Started]({{< ref "getting-started" >}}) and [Site Configuration]({{< ref "configuration#site-configuration" >}}) sections for parameter details. The author information is provided in the languages configuration file. Refer to the [Getting Started]({{< ref "getting-started" >}}) and [Language Configuration]({{< ref "configuration##language-and-i18n" >}}) sections for parameter details.
Additionally, any Markdown content that is provided in the homepage content will be placed below the author profile. This allows extra flexibility for displaying a bio or other custom content using shortcodes. Additionally, any Markdown content that is provided in the homepage content will be placed below the author profile. This allows extra flexibility for displaying a bio or other custom content using shortcodes.

BIN
exampleSite/content/docs/shortcodes/abstract.jpg 100644
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

30
exampleSite/content/docs/shortcodes.md → exampleSite/content/docs/shortcodes/index.md
View File

@ -95,6 +95,36 @@ data: {
You can see some additional Chart.js examples on the [charts samples]({{< ref "charts" >}}) page. You can see some additional Chart.js examples on the [charts samples]({{< ref "charts" >}}) page.
## Figure
Congo includes a `figure` shortcode for adding images to content. The shortcode replaces the base Hugo functionality in order to provide additional performance benefits.
Images included using `figure` will be optimised using Hugo Pipes and scaled in order to provide images appropriate to different device resolutions.
The `figure` shortcode accepts five parameters:
<!-- prettier-ignore-start -->
|Parameter|Description|
|---|---|
|`src`|**Required.** The filename of the image. This image must be a [page resource](https://gohugo.io/content-management/page-resources/) bundled with the page.|
|`alt`|The alternate text for the image.|
|`caption`|The image caption to be displayed below the image.|
|`class`|Additional CSS classes to add to the image.|
`href`|The URL that the image should be linked to.|
<!-- prettier-ignore-end -->
**Example:**
```md
{{</* figure
src="abstract.jpg"
alt="Abstract purple artwork"
caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)"
*/>}}
```
{{< figure src="abstract.jpg" alt="Abstract purple artwork" caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)" >}}
## Icon ## Icon
`icon` outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size. `icon` outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size.

4
exampleSite/content/docs/version-2/_index.md
View File

@ -26,9 +26,9 @@ Implementing this new version has also removed some Tailwind plugin dependencies
A highly requested feature, Congo is now multilingual! If you publish your content in multiple languages, the site will be built with all the translations available. A highly requested feature, Congo is now multilingual! If you publish your content in multiple languages, the site will be built with all the translations available.
<div class="text-2xl text-center" style="font-size: 2.8rem">:flag-au: :de: :fr: :es: :brazil: :cn:</div> <div class="text-2xl text-center" style="font-size: 2.8rem">:flag-au: :de: :fr: :es: :cn: :brazil: :tr:</div>
Thanks to submissions from the community, Congo has already been translated into [six languages](https://github.com/jpanther/tree/dev/i18n) with more to be added over time. By the way, pull requests for new languages are always welcome! Thanks to submissions from the community, Congo has already been translated into [seven languages](https://github.com/jpanther/congo/tree/dev/i18n) with more to be added over time. By the way, pull requests for new languages are always welcome!
## RTL language support ## RTL language support