diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 647f968..9a414b5 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -36,11 +36,11 @@ and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Version * Improve the list template to be more considerable to easy eyeing of the posts. * Fallback themes are now enforced to be implemented into two themes: one for light and one for dark theme. -This is changed from a single `_index` Base16 scheme to `_{dark,light}` Base16 scheme. +This is changed from a single `+_index+` Base16 scheme to `+_{dark,light}+` Base16 scheme. The Hugo theme also has fallbacks for certain cases. ** If the user gives only one system theme, the Hugo theme will generate the appropriate counterpart theme. -E.g., if there is only `_dark`, the Hugo theme will generate the light theme. +E.g., if there is only `+_dark+`, the Hugo theme will generate the light theme. ** If given neither, fallback themes will be used. @@ -54,10 +54,10 @@ E.g., if there is only `_dark`, the Hugo theme will generate the light theme. * Format the files correctly as specified from the EditorConfig file. -== Removed +=== Removed -* Setting the default theme with `./data/more-contentful/themes/_index.{yaml,json,toml}`. -It has been replaced with setting system themes with `./data/more-contentful/themes/_{light,dark}.{yaml,json,toml}`. +* Setting the default theme with `+./data/more-contentful/themes/_index.{yaml,json,toml}+`. +It has been replaced with setting system themes with `+./data/more-contentful/themes/_{light,dark}.{yaml,json,toml}+`. diff --git a/README.adoc b/README.adoc index 443c6c6..c9f0487 100644 --- a/README.adoc +++ b/README.adoc @@ -307,14 +307,14 @@ The schemes are then pressed against a template (i.e., link:./assets/templates/t ---- By default, this theme enforces setting system themes with a light and a dark theme. -You can set the custom themes for both system light and dark theme for your website by naming them `_light.{json,toml,yaml}` and `_dark.{json,toml,yaml}`, respectively. +You can set the custom themes for both system light and dark theme for your website by naming them `+_light.{json,toml,yaml}+` and `+_dark.{json,toml,yaml}+`, respectively. This theme has kept some usecases in mind: -* If either theme is missing, the theme will generate one for you with the assumption that the user-given color scheme is set correctly (e.g., `_dark` is a dark theme and the theme will generate a light theme). +* If either theme is missing, the theme will generate one for you with the assumption that the user-given color scheme is set correctly (e.g., `+_dark+` is a dark theme and the theme will generate a light theme). The color generation for the counterpart theme is not yet great (or even acceptable) so it is recommended to handcraft both of the system themes. * If neither system themes are given, the Hugo theme will use the fallback system themes which can be found at link:./data/more-contentful/themes[`./data/more-contentful/themes`]. -The fallback themes are named `_{dark,light}_fallback.yaml`. +The fallback themes are named `+_{dark,light}_fallback.yaml+`. It is discouraged to change or override them. For practical purposes, you should build your own color palette. @@ -388,7 +388,7 @@ If the social platform icon is not included in the icon set, it will not have an Thus, it is recommended to display the text (i.e., `useImage = false`) instead. -=== Editing the theme +=== Extending the theme There are mainly two situations when you customize the theme. @@ -416,15 +416,47 @@ curl --silent --location https://api.github.com/repos/foo-dogsquared/hugo-theme- TIP: You can then put the one-liner in a script or in a Makefile to make it easier. Otherwise, if you want to fully customize the theme, you can vendor this project into yours. -Also, see the <> for more information. +Also, see the <> for more information. * The recommended way is to fork the project, make your customizations there, and use it. -* If you use Hugo modules, you can run `hugo mod vendor` and it will pull the files in `_vendor/`. +* If you use Hugo modules, you can run `hugo mod vendor` and it will pull the files in `+_vendor/+`. * If you don't want to create another repo for the customized version of the theme intended only for one Hugo site, make the project as a https://www.atlassian.com/git/tutorials/git-subtree[a Git subtree] preferably in `themes/more-contentful/`. +=== Theme conventions and guidelines + +If you're planning on extending the theme, warts and all, it can be frustrating to start by diving into the source code head-first. +Here's a list of guidelines and conventions that the theme uses. +It isn't exhaustive but it is a start. + +Like most guidelines, they are not followed to the absolute and not set in stone. +You can also see the <> for more details. + +* For editing the CSS files... + +** It uses link:http://getbem.com/introduction/[BEM-style class names]. + +** Each of the theme will generate a custom property of `--base00`, `--base01`, `--base02` up to `--base0F`. +This should be treated as a palette, nothing more. + +** To set a color with a role, put it under a custom property and use that instead (e.g., if `--base05` will be used mainly for text color, then create a custom property named `--text-color` to be used for any text-related styles that changes its color). +This will make maintaining the theme easier. +You can see a sample of this from link:./assets/scss/main.scss[`./assets/scss/main.scss`] defined at `:root`. + +** Place all CSS global variables at link:./assets/scss/main.scss[`./assets/scss/main.scss`]. + +* For setting assets in the theme, SVG icons are preferred. +It should be optimized or sanitized to be able to easily set the color along with the text. +In this case, the theme has a preferred use for link:https://heroicons.com/[Heroicons] which has the added bonus of consistency. + +* If an element should hold stateful data, make full use of link:https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes[`data-*` attributes]. + +* Don't place `