From 18ed642ae4658b93b75fa200ce23e2626bfc8070 Mon Sep 17 00:00:00 2001 From: James Panther <4462786+jpanther@users.noreply.github.com> Date: Tue, 17 Aug 2021 15:35:04 +1000 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=20Consolidate=20author=20configura?= =?UTF-8?q?tion=20options?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 4 ++ README.md | 9 +---- config/_default/author.toml | 34 ---------------- config/_default/config.toml | 45 +++++++++++++++------ config/_default/params.toml | 3 +- exampleSite/content/docs/configuration.md | 27 ++++++++++++- exampleSite/content/docs/getting-started.md | 12 +++--- 7 files changed, 71 insertions(+), 63 deletions(-) delete mode 100644 config/_default/author.toml diff --git a/CHANGELOG.md b/CHANGELOG.md index 87b4be32..725b24b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Consolidated author configuration parameters into `config.toml` + ### Fixed - Fixes URLs being incorrect in some cases when the site is deployed in a subfolder diff --git a/README.md b/README.md index 6ceb5aa5..511be018 100644 --- a/README.md +++ b/README.md @@ -69,19 +69,12 @@ A few things you need to set for a new installation: baseURL = "https://your_domain.com" languageCode = "en-AU" - title = "My awesome website" -``` - -It's also useful to set the author configuration in the `config/_default/author.toml` file. You can also add links to your profiles here to enable them in the theme. - -```toml -# config/_default/author.toml [author] name = "Your name" links = [ - { twitter = "https://twitter.com/username" } + { twitter = "https://twitter.com/jpanther" } ] ``` diff --git a/config/_default/author.toml b/config/_default/author.toml deleted file mode 100644 index 5aa0e4f9..00000000 --- a/config/_default/author.toml +++ /dev/null @@ -1,34 +0,0 @@ -# -- Site Author Details -- -# To display the author box below each article, configure the settings below. -# The author image should be placed inside the `/static` folder. -# Uncomment any links to enable them. The icons will be displayed in the order listed. - -[author] - # name = "Your name here" - # image = "/img/author.jpg" - # links = [ - # { email = "mailto:hello@your_domain.com" }, - # { link = "https://link-to-some-website.com/" }, - # { codepen = "https://codepen.io/username" }, - # { dev = "https://dev.to/username" }, - # { discord = "https://discord.gg/invitecode" }, - # { dribbble = "https://dribbble.com/username" }, - # { facebook = "https://facebook.com/username" }, - # { github = "https://github.com/username" }, - # { gitlab = "https://gitlab.com/username" }, - # { instagram = "https://instagram.com/username" }, - # { keybase = "https://keybase.io/username" }, - # { lastfm = "https://lastfm.com/user/username" }, - # { linkedin = "https://linkedin.com/in/username" }, - # { mastodon = "https://mastodon.instance/@username" }, - # { medium = "https://medium.com/username" }, - # { reddit = "https://reddit.com/user/username" }, - # { slack = "https://workspace.url/team/userid" }, - # { snapchat = "https://snapchat.com/add/username" }, - # { soundcloud = "https://soundcloud.com/username" }, - # { steam = "https://steamcommunity.com/profiles/userid" }, - # { tiktok = "https://tiktok.com/@username" }, - # { twitch = "https://twitch.tv/username" }, - # { twitter = "https://twitter.com/username" }, - # { youtube = "https://youtube.com/username" }, - # ] diff --git a/config/_default/config.toml b/config/_default/config.toml index fda0ff81..b9e1ebd6 100644 --- a/config/_default/config.toml +++ b/config/_default/config.toml @@ -1,23 +1,44 @@ # -- Site Configuration -- +# Refer to the theme docs for more details about each of these parameters. +# https://jpanther.github.io/Congo/docs/getting-started/ + theme = "congo" -# Speficiy the base URL for the website. # baseURL = "https://your_domain.com/" - -# The language code of the language that the website is written in. -# This can be a base language (ie. "en") or a specific variant (ie. "en-AU"). languageCode = "en" -# The website title. This will be displayed in the site header. title = "Congo" - -# A default copyright message is generated automatically. -# Uncomment the line below to provide a custom copyright Markdown string. # copyright = "Copy, _right?_ :thinking_face:" -# To automatically convert strings such as :bang: to emoji, set this to true. enableEmoji = true - -# Congo will generate a robots file that allows search engines to index -# the entire site. If you don't want a robots file, set this to false. enableRobotsTXT = true + +[author] + # name = "Your name here" + # image = "img/author.jpg" + # links = [ + # { email = "mailto:hello@your_domain.com" }, + # { link = "https://link-to-some-website.com/" }, + # { codepen = "https://codepen.io/username" }, + # { dev = "https://dev.to/username" }, + # { discord = "https://discord.gg/invitecode" }, + # { dribbble = "https://dribbble.com/username" }, + # { facebook = "https://facebook.com/username" }, + # { github = "https://github.com/username" }, + # { gitlab = "https://gitlab.com/username" }, + # { instagram = "https://instagram.com/username" }, + # { keybase = "https://keybase.io/username" }, + # { lastfm = "https://lastfm.com/user/username" }, + # { linkedin = "https://linkedin.com/in/username" }, + # { mastodon = "https://mastodon.instance/@username" }, + # { medium = "https://medium.com/username" }, + # { reddit = "https://reddit.com/user/username" }, + # { slack = "https://workspace.url/team/userid" }, + # { snapchat = "https://snapchat.com/add/username" }, + # { soundcloud = "https://soundcloud.com/username" }, + # { steam = "https://steamcommunity.com/profiles/userid" }, + # { tiktok = "https://tiktok.com/@username" }, + # { twitch = "https://twitch.tv/username" }, + # { twitter = "https://twitter.com/username" }, + # { youtube = "https://youtube.com/username" }, + # ] diff --git a/config/_default/params.toml b/config/_default/params.toml index 99730681..93d02588 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -2,7 +2,8 @@ # These options control how the theme functions and allow you to # customise the display of your website. # -# Refer to the README for more details about each of these parameters. +# Refer to the theme docs for more details about each of these parameters. +# https://jpanther.github.io/Congo/docs/configuration/#theme-parameters [homepage] layout = "page" # valid options: page, profile, custom diff --git a/exampleSite/content/docs/configuration.md b/exampleSite/content/docs/configuration.md index f0720377..e1600225 100644 --- a/exampleSite/content/docs/configuration.md +++ b/exampleSite/content/docs/configuration.md @@ -21,7 +21,32 @@ The default theme configuration is documented in each file so you can freely adj As outlined in the [installation instructions](/docs/installation/#set-up-your-configuration-files), you should adjust your theme configuration by modifying the files in the `config/_default/` folder of your Hugo project and delete the `config.toml` file in your project root. {{< /alert >}} -## Parameters +## Site Configuration + +Standard Hugo configuration variables are respected throughout the theme, however there are some specific things that should be configured for the best experience. + +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`). + + +|Name|Type|Default|Description| +| --- | --- | --- | --- | +|`theme`|string|`"congo"`|This must be set to `"congo"` for the theme to function.| +|`baseURL`|string|_Not set_|The URL to the root of the website.| +|`languageCode`|string|`"en"`|The language of the website. It can be a top-level language (ie. `"en"`) or a sub-variant (ie. `"en-AU"`)." +|`title`|string|`"Congo"`|The title of the website. This will be displayed in the site header and footer.| +|`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`. +|`enableEmoji`|boolean|`true`|Whether emoji strings in content should be converted to emoji symbols.| +|`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.| +|`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.| +|`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.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.| +|`[taxonomies]`||_Not set_|Refer to the [Hugo docs](https://gohugo.io/content-management/taxonomies/) for taxonomy configuration.| + + +## Theme Parameters Congo provides a large number of configuration parameters that control how the theme functions. The table below outlines every available parameter in the `config/_default/params.toml` file. diff --git a/exampleSite/content/docs/getting-started.md b/exampleSite/content/docs/getting-started.md index 6dd36e4a..9ddc2d7f 100644 --- a/exampleSite/content/docs/getting-started.md +++ b/exampleSite/content/docs/getting-started.md @@ -22,22 +22,20 @@ A few things you need to set for a new installation: baseURL = "https://your_domain.com" languageCode = "en-AU" - title = "My awesome website" -``` - -It's also useful to set the author configuration in the `config/_default/author.toml` file. You can also add links to your profiles here to enable them in the theme. - -```toml -# config/_default/author.toml [author] name = "Your name" +image = "img/author.jpg" links = [ { 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. + +Further detail about these configuration options is covered in the [Configuration](/docs/configuration/) section. + ## Organising content 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.