diff --git a/README.md b/README.md index 53677956..e7061790 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,13 @@ Some works are still in progress. See [TODOS](#todos) below. ## Install 1. clone cactus to your hugo site's `themes` folder. + ``` git clone https://github.com/monkeyWzr/hugo-theme-cactus.git themes/cactus ``` 2. change your theme to cactus in your site config + ```toml # config.toml @@ -22,6 +24,7 @@ theme = "cactus" 3. config your site. See [Config] or a [complete config sample](exampleSite/config.toml) 4. test your site + ``` hugo server ``` @@ -75,35 +78,37 @@ weight = 4 ### Homepage settings -* description: description will be displayed in the homepage. Markdown syntax is supported in the description string. +- description: description will be displayed in the homepage. Markdown syntax is supported in the description string. + ```toml [params] description = "Hugo is a general-purpose website framework. Technically speaking, Hugo is a static site generator. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website’s end users and an ideal writing experience for website authors." ``` -* set your main section (used as the link for the "writings" title on the homepage) +- set your main section (used as the link for the "writings" title on the homepage) ```toml [params] mainSection = "posts" ``` -* change the default main section title from Writings, to something else: +- change the default main section title from Writings, to something else: ```toml [params] mainSectionTitle = "Blog" ``` -* Show only the 5 most recent posts (default) +- Show only the 5 most recent posts (default) ```toml [params] showAllPostsOnHomePage = false postsOnHomePage = 5 ``` -* show all posts + +- show all posts ```toml [params] @@ -111,14 +116,15 @@ weight = 4 postsOnHomePage = 5 # this option will be ignored ``` -* show tagsoverview (default) or not -* +- show tagsoverview (default) or not +- + ```toml [params] tagsOverview = true ``` -* show projects list (default) or not. +- show projects list (default) or not. ```toml [params] @@ -134,20 +140,21 @@ Create your projects data file `data/projects.yaml|toml|json`. Hugo support yaml for former hexo cactus users: please assign your json array to a `list` key. for example, `data/projects.json`: + ```json { - "list": [ - { - "name":"Hexo", - "url":"https://hexo.io/", - "desc":"A fast, simple & powerful blog framework" - }, - { - "name":"Font Awesome", - "url":"http://fontawesome.io/", - "desc":"The iconic font and CSS toolkit" - } - ] + "list": [ + { + "name": "Hexo", + "url": "https://hexo.io/", + "desc": "A fast, simple & powerful blog framework" + }, + { + "name": "Font Awesome", + "url": "http://fontawesome.io/", + "desc": "The iconic font and CSS toolkit" + } + ] } ``` @@ -182,6 +189,7 @@ copyright = "Zeran Wu" # cactus theme will use site title if copyright is not se ### Comments Comments is disabled by default. Enable comments in your `.Site.Params`. + ```toml [params] [params.comments] @@ -190,6 +198,7 @@ Comments is disabled by default. Enable comments in your `.Site.Params`. ``` You can also enable/disable comments per post. in your posts' front matter, add: + ```yaml comments: true ``` @@ -229,11 +238,13 @@ default config: Cactus uses hugo's bulit in analytics templates. Check [hugo's documents](https://gohugo.io/templates/internal#google-analytics) for details. Set you tracking id in your site config. + ```toml googleAnalytics = "UA-XXXXXXXX-XX" # or G-XXXXXXXX if you are using Google Analytics v4 (gtag.js) ``` If you are using Google Analytics v3 (analytics.js), you can switch to asynchronous tracking by set `params.googleAnalyticsAsync` to `true`. + ```toml [params] googleAnalyticsAsync = true # not required @@ -252,22 +263,55 @@ The rss link will be `https://example.com/index.xml` assuming your `baseURL` is Please also check [Configure RSS](https://gohugo.io/templates/rss/#configure-rss) +### Related content + +Cactus supports hugo's automatic related content. You can enable it in your site config: + +```toml +[related] + includeNewer = true + threshold = 10 + toLower = true + + [[related.indices]] + name = "keywords" + weight = 80 + + [[related.indices]] + name = "title" + weight = 80 + + [[related.indices]] + name = "tags" + weight = 100 + + [[related.indices]] + name = "date" + weight = 60 + pattern = "2006" +``` + +Please also check [Related Content](https://gohugo.io/content-management/related/) & [Better Relationships in Hugo with Hugo's Related Content](https://www.regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/). + ### Mathjax Cactus supports mathjax. Just add `mathjax` option in your site config: + ```toml [params] mathjax = true # not required ``` You can also enable/disable mathjax per post. In your posts' front matter, add: + ```yaml mathjax: true # or false ``` The site config will be ignored when `mathjax` option exists in front matter. -### Archive +### Archive + Pagination on posts archive can be disabled to show all posts in chronological order ```toml @@ -285,7 +329,7 @@ Pagination on posts archive can be disabled to show all posts in chronological o - [ ] toc template - [ ] Customizable copyright year - [ ] gallery -- [ ] expose [mathjax configuration](https://docs.mathjax.org/en/latest/web/configuration.html#web-configuration) +- [ ] expose [mathjax configuration](https://docs.mathjax.org/en/latest/web/configuration.html#web-configuration) ## License diff --git a/layouts/partials/related.html b/layouts/partials/related.html new file mode 100644 index 00000000..2c5a0831 --- /dev/null +++ b/layouts/partials/related.html @@ -0,0 +1,9 @@ +{{ $related := .Site.RegularPages.Related . | first 5 }} {{ with $related }} +