From 7c8367f7c4715963504bef0e7c36e2b9d32eaa5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luiz=20F=2E=20A=2E=20de=20Pr=C3=A1?= Date: Sun, 29 May 2022 16:28:04 -0300 Subject: Add docs folder with wiki content --- README.md | 5 +- docs/analytics.md | 1 + docs/comment-system.md | 1 + docs/configurations.md | 345 ++++++++++++++++++++++++++++++++++++++++++++++ docs/contributing.md | 1 + docs/home.md | 18 +++ docs/multilingual-mode.md | 73 ++++++++++ docs/quick-start.md | 23 ++++ 8 files changed, 464 insertions(+), 3 deletions(-) create mode 100644 docs/analytics.md create mode 100644 docs/comment-system.md create mode 100644 docs/configurations.md create mode 100644 docs/contributing.md create mode 100644 docs/home.md create mode 100644 docs/multilingual-mode.md create mode 100644 docs/quick-start.md diff --git a/README.md b/README.md index e09e7a4..c5b0b5e 100644 --- a/README.md +++ b/README.md @@ -29,10 +29,9 @@ See [here](https://hugo-coder.netlify.app/). 2. Configure your `config.toml`. You can either use [this minimal configuration](https://github.com/luizdepra/hugo-coder/wiki/Configurations#complete-example) as a base, or look for a complete explanation about all configurations [here](https://github.com/luizdepra/hugo-coder/wiki/Configurations). The [`config.toml`](https://github.com/luizdepra/hugo-coder/blob/master/exampleSite/config.toml) inside the [`exampleSite`](https://github.com/luizdepra/hugo-coder/tree/master/exampleSite) is also a good reference. 3. Build your site with `hugo server` and see the result at `http://localhost:1313/`. -## Extra Guides - -* [Multilingual Mode](https://github.com/luizdepra/hugo-coder/wiki/Multilingual-Mode) +## Documentations +See [`docs`](docs/home.md) folder. ## License diff --git a/docs/analytics.md b/docs/analytics.md new file mode 100644 index 0000000..00d7bdd --- /dev/null +++ b/docs/analytics.md @@ -0,0 +1 @@ +WIP diff --git a/docs/comment-system.md b/docs/comment-system.md new file mode 100644 index 0000000..00d7bdd --- /dev/null +++ b/docs/comment-system.md @@ -0,0 +1 @@ +WIP diff --git a/docs/configurations.md b/docs/configurations.md new file mode 100644 index 0000000..8472fb0 --- /dev/null +++ b/docs/configurations.md @@ -0,0 +1,345 @@ +# Configurations + +* [About Hugo Configurations](#about-hugo-configurations) + * [Analytics](#analytics) + * [Google Analytics](#google-analytics) + * [Google Tag Manager](#google-tag-manager) + * [Fathom Analytics](#fathom-analytics) + * [Plausible Analytics](#plausible-analytics) + * [Goat Counter](#goat-counter) + * [Cloudflare](#cloudflare) + * [Matomo](#matomo) + * [Commenting Systems](#commenting-systems) + * [Disqus](#disqus) + * [Commento](#commento) + * [Utterances](#utterances) +* [Theme Parameters](#theme-parameters) + * [Social Icons Configuration](#social-icons-configuration) + * [Menu Items Configurations](#menu-items-configurations) + * [CSP](#csp) +* [Complete Example](#complete-example) +* [Front Matter](#front-matter) + * [Posts](#posts) + +## About Hugo Configurations + +This theme supports: + +* Analytics + * [Google Analytics](https://developers.google.com/analytics) + * [Google Tag Manager](https://developers.google.com/tag-manager) + * [Fathom Analytics](https://usefathom.com/) + * [Plausible Analytics](https://plausible.io/) + * [Goat Counter](https://www.goatcounter.com/) + * [Cloudflare](https://www.cloudflare.com/analytics/) + * [Matomo](https://matomo.org/) +* Commenting Systems + * [Disqus](https://disqus.com/) + * [Commento](https://commento.io/) + * [Utterances](https://utteranc.es/) + +### Analytics + +#### Google Analytics + +Follow [these steps](https://gohugo.io/templates/internal/#configure-google-analytics). + +#### Google Tag Manager + +```toml +[params.googleTagManager] + id = "gid" +``` + +#### Fathom Analytics + +```toml +[params.fathomAnalytics] + siteID = "ABCDE" + serverURL = "cdn.usefathom.com" # (optionnal) Replace if you use a custom domain +``` + +#### Plausible Analytics + +```toml +[params.plausibleAnalytics] + domain = "example.com" + serverURL = "plausible.io" # (optionnal) Replace if you use a custom domain +``` + +#### Goat Counter + +```toml +[params.goatCounter] + code = "code" # You will access your account at https://[code].goatcounter.com +``` + +#### Cloudflare + +```toml +[params.cloudflare] + token = "token" +``` + +#### Matomo + +```toml +[params.matomo] + siteID = "ABCDE" + serverURL = "analytics.example.com" +``` + +### Commenting Systems + +Comments are displayed within post pages, but can be disabled with `disableComments` front-matter. + +#### Disqus + +Follow [these steps](https://gohugo.io/content-management/comments/#configure-disqus). + +#### Commento + +```toml +[params] + commentoURL = "https://cdn.commento.io" # Replace if you use a custom domain +``` + +#### Utterances + +```toml +[params.utterances] + repo = "" # https://utteranc.es/#heading-repository + issueTerm = "" # https://utteranc.es/#heading-mapping + label = "" # https://utteranc.es/#heading-issue-label + theme = "" # https://utteranc.es/#heading-theme +``` + +## Theme Parameters + +These are all the parameters used by `hugo-coder` theme. + +| Name | Type | Required | Description | Default | Example | +| ----------------------------- | ------ | -------- | ------------------------------------------------ | -------------------------------- | ------------------------------------------------ | +| author | string | Yes | Author name. | | `"John Doe"` | +| info | string | Yes | An headline, job title or similar. | | `"Full Stack Developer"` | +| description | string | Yes | Description of the site. | | `"John Doe's personal website"` | +| keywords | string | Yes | Site keywords. | | `"blog,developer,personal"` | +| avatarURL | string | No | Photo of the author. | | `"images/avatar.jpg"` | +| gravatar | string | No | Gravatar photo of the author | | `"john.doe@example.com"` | +| favicon_32 | string | No | Custom path to a 32x32 favicon. | `"/img/favicon-32x32.png"` | `"/img/favicon-32x32.png"` | +| favicon_16 | string | No | Custom path to a 16x16 favicon. | `"/img/favicon-16x16.png"` | `"/img/favicon-16x16.png"` | +| touchIcon | string | No | Custom path to a touch-icon | `"/images/apple-touch-icon.png"` | `"/images/apple-touch-icon.png"` | +| since | string | No | Date shown in the footer before now year | | `"2020"` | +| maxSeeAlsoItems | number | No | Series see also post count | `5` | `10` | +| commit | string | No | Show the last git commit in the footer | | `"https://github.com/luizdepra/hugo-coder/tree/"`| +| rtl | bool | No | Enable the Right To Left mode. | `false` | `true` or `false` | +| math | bool | No | Enable MathJax Module and add JS into your site. | `false` | `true` or `false` | +| katex | bool | No | Enable katex for all content types. | `false` | `true` or `false` | +| colorScheme | string | No | Specify light/dark colorscheme | `"auto"` | `"auto"` or `"light"` or `"dark"` | +| hideColorSchemeToggle | bool | No | If true, hides the color sheme toggle | `false` | `true` or `false` | +| customCSS | list | No | Add extra CSS files to the website. | [] | `["css/extra-style.css"]` | +| customSCSS | list | No | Add extra SCSS files to the website. | [] | `["scss/extra-style.scss"]` | +| customJS | list | No | Add extra JS files to the website. | [] | `["js/extra-script.js"]` | +| enableTwemoji | bool | No | Adds support for Twemoji | `false` | `true` or `false` | + +### Social Icons Configuration + +Social Icons are optional. To use them you will need to set at least all the following required parameters for each icon. + +| Configuration | Type | Required | Description | Example | +| -------------- | ------ | -------- | ---------------------------------------- | ------------------------------- | +| name | string | Yes | Icon name. | `"Github"` | +| icon | string | Yes | ForkAwesome icon classes. | `"fa fa-github"` | +| weight | int | Yes | Icon order. | `1` | +| url | string | Yes | URL to redirect. | `"https://github.com/johndoe/"` | + +An example: + +```toml +[[params.social]] + name = "Github" + icon = "fa fa-github fa-2x" + weight = 1 + url = "https://github.com/johndoe/" +[[params.social]] + name = "Gitlab" + icon = "fa fa-gitlab fa-2x" + weight = 2 + url = "https://gitlab.com/johndoe/" +[[params.social]] + name = "Twitter" + icon = "fa fa-twitter fa-2x" + weight = 3 + url = "https://twitter.com/johndoe/" +``` + +### Menu Items Configurations + +Menu Items are optional. To use them you will need to set all the following required parameters for each icon. + +| Configuration | Type | Required | Description | Example | +| -------------- | ------ | -------- | ---------------------------------------- | ------------------------------- | +| name | string | Yes | Menu Item name. | `"Posts"` | +| weight | int | Yes | Menu Item order. | `1` | +| url | string | Yes | URL to redirect. | `"/posts/"` | +| target | string | No | URL target attribute. | `"_blank"` | +| rel | string | No | URL rel attribute. | `"alternate"` | +| type | string | No | URL type attribute. | `"application/rss+xml"` | + +An example: + +```toml +[[menu.main]] + name = "Blog" + weight = 1 + url = "posts/" +[[menu.main]] + name = "About" + weight = 2 + url = "about/" +``` + +### CSP + +CSP stands for [Content Security Policy](https://developers.google.com/web/fundamentals/security/csp). These configurations are optional. To use them you will need to set all the following required parameters. See [here](https://developers.google.com/web/fundamentals/security/csp#policy_applies_to_a_wide_variety_of_resources) for reference. + +| Configuration | Type | Required | Description | Example | +| -------------- | ----------- | -------- | ----------- | ------------------------------- | +| childsrc | string list | Yes | | `["'self'"]` | +| fontsrc | string list | Yes | | `["'self'"]` | +| formaction | string list | Yes | | `["'self'"]` | +| framesrc | string list | Yes | | `["'self'"]` | +| imgsrc | string list | Yes | | `["'self'"]` | +| objectsrc | string list | Yes | | `["'self'"]` | +| stylesrc | string list | Yes | | `["'self'"]` | +| scriptsrc | string list | Yes | | `["'self'"]` | +| prefetchsrc | string list | Yes | | `["'self'"]` | + +An example: + +```toml +[params.csp] + childsrc = ["'self'"] + fontsrc = [ + "'self'", + "https://fonts.gstatic.com", + "https://cdn.jsdelivr.net/" + ] + formaction = ["'self'"] + framesrc = ["'self'"] + imgsrc = ["'self'"] + objectsrc = ["'none'"] + stylesrc = [ + "'self'", + "'unsafe-inline'", + "https://fonts.googleapis.com/", + "https://cdn.jsdelivr.net/" + ] + scriptsrc = [ + "'self'", + "'unsafe-inline'", + "https://www.google-analytics.com" + ] + prefetchsrc = ["'self'"] +``` + +## Complete Example + +This is a complete configuration example with some recommended values. + +```toml +baseurl = "http://www.example.com" +title = "johndoe" +theme = "hugo-coder" +languagecode = "en" +defaultcontentlanguage = "en" + +paginate = 20 + +pygmentsstyle = "bw" +pygmentscodefences = true +pygmentscodefencesguesssyntax = true + +disqusShortname = "yourdiscussshortname" + +[params] + author = "John Doe" + info = "Full Stack DevOps and Magician" + description = "John Doe's personal website" + keywords = "blog,developer,personal" + avatarurl = "images/avatar.jpg" + #gravatar = "john.doe@example.com" + + favicon_32 = "/img/favicon-32x32.png" + favicon_16 = "/img/favicon-16x16.png" + + since = 2019 + + enableTwemoji = true + + colorScheme = "auto" + hidecolorschemetoggle = false + + customCSS = ["css/custom.css"] + customSCSS = ["scss/custom.scss"] + customJS = ["js/custom.js"] + +[taxonomies] + category = "categories" + series = "series" + tag = "tags" + author = "authors" + +# Social links +[[params.social]] + name = "Github" + icon = "fa fa-github fa-2x" + weight = 1 + url = "https://github.com/johndoe/" +[[params.social]] + name = "Gitlab" + icon = "fa fa-gitlab fa-2x" + weight = 2 + url = "https://gitlab.com/johndoe/" +[[params.social]] + name = "Twitter" + icon = "fa fa-twitter fa-2x" + weight = 3 + url = "https://twitter.com/johndoe/" + +# Menu links +[[menu.main]] + name = "Blog" + weight = 1 + url = "posts/" +[[menu.main]] + name = "About" + weight = 2 + url = "about/" +``` + +## Front Matter + +Hugo documentation: https://gohugo.io/content-management/front-matter + +This theme includes one content type: + +* [Posts](#posts), useful to display blog posts + +### Posts + +These are the front matter variables used by `hugo-coder` theme. + +| Name | Type | Required | Description | Default | Example | +| ---------------- | ------ | -------- | -------------------------------------------------- | ------- | ----------------------------------------------------------------------------- | +| tags | list | No | Add tag(s) to this post. | | `["Hugo", "Go"]` | +| categories | list | No | Add categorie(s) to this post. | | `["Hugo", "Go"]` | +| series | list | No | Add series to this post (used by OpenGraph). | | `["Theme Demo"]` | +| author | list | No | Add author to this post. | | `["John Doe"]` | +| externalLink | string | No | Link to an external post. | | `"https://github.com/luizdepra/hugo-coder/wiki"` | +| featuredImage | string | No | Link/path to add an image below post metadata. | | `"https://github.com/luizdepra/hugo-coder/blob/master/images/screenshot.png"` | +| math | bool | No | If true, MathJax is enabled only for this post. | `false` | `true` or `false` | +| katex | bool | No | If true, katex is enabled only for this post. | `false` | `true` or `false` | +| disableComments | bool | No | If true, comments are disabled. | `false` | `true` or `false` | + +> "tags", "categories", "series" and "authors" are taxonomies defined in the `config.toml` file. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..00d7bdd --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1 @@ +WIP diff --git a/docs/home.md b/docs/home.md new file mode 100644 index 0000000..0fe55e5 --- /dev/null +++ b/docs/home.md @@ -0,0 +1,18 @@ +# Welcome to the hugo-coder docs! + +## Basic Usage + +* [Quick Start](docs/quick-start.md) +* [Configurations](docs/configurations.md) + +## Extra Guides + +* [Multilingual Mode](docs/multilingual-mode.md) +* [Comment System](docs/comment-system.md) +* [Analytics](docs/analytics.md) + +## Maintainers & Developers + +* [Contributing](docs/contributing.md) + + diff --git a/docs/multilingual-mode.md b/docs/multilingual-mode.md new file mode 100644 index 0000000..8384e6d --- /dev/null +++ b/docs/multilingual-mode.md @@ -0,0 +1,73 @@ +# Multilingual-Mode + +* [Available Languages](#available-languages) +* [Configure Languages](#configure-languages) +* [Translation File Example](#translation-file-example) + +## Available Languages + +This theme supports the following languages: + +- Arabic +- Bengali +- Czech +- German +- English +- Spanish +- Finnish +- French +- Hebrew +- Hindi +- Hungarian +- Italian +- Japanese +- Malay +- Dutch +- Polish +- Brazilian Portuguese +- Romanian +- Russian +- Swedish +- Slovak +- Turkish +- Simplified Chinese +- Taiwan Chinese + +## Configure languages + +Go to [this Hugo documentation page](https://gohugo.io/content-management/multilingual/#configure-languages) to configure one or multiple languages for your website. + +## Translation File Example + +```toml +[category] +other = "category" + +[tag] +other = "tag" + +[series] +other = "series" + +[author] +other = "author" + +[reading_time] +one = "One-minute read" +other = "{{ .Count }}-minute read" + +[page_not_found] +other = "Page Not Found" + +[page_does_not_exist] +other = "Sorry, this page does not exist." + +[head_back] +other = "You can head back to homepage." + +[powered_by] +other = "Powered by" + +[see_also] +other = "See also in" +``` diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..00012c8 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,23 @@ +# Quick Start + +To start using `hugo-coder`: + +1. Add the repository into your Hugo Project repository as a submodule, `git submodule add https://github.com/luizdepra/hugo-coder.git themes/coder`. +2. Configure your `config.toml`. You can either use the [this minimal configuration](Configurations#complete-example) as a base, or look for a complete explanation about all configurations [here](https://github.com/luizdepra/hugo-coder/wiki/Configurations). The [`config.toml`](https://github.com/luizdepra/hugo-coder/blob/master/exampleSite/config.toml) inside the [exampleSite](https://github.com/luizdepra/hugo-coder/tree/master/exampleSite) from the `exampleSite` is also a good reference. +3. Build your site with `hugo serve` and see the result at `http://localhost:1313/`. + +If you just want to test this theme, go to [this page](https://themes.gohugo.io/theme/hugo-coder/). + +You can also clone or download it, then run these commands: + +``` +git clone https://github.com/luizdepra/hugo-coder.git + +cd hugo-coder + +make demo +``` + +You'll see the result at [http://localhost:1313/](http://localhost:1313/). + +> These last two methods don't use the same content directory, the first one leads to 404 pages for some pages. More info [here](https://github.com/gohugoio/hugoThemes#adding-a-theme-to-the-list). \ No newline at end of file -- cgit v1.2.3