Add docs folder with wiki content

Luiz F. A. de Prá

29.28.2022 7c8367f7c4715963504bef0e7c36e2b9d32eaa5e

Add docs folder with wiki content

 README.md

@@ -29,10 +29,9 @@
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
## Documentations

* [Multilingual Mode](https://github.com/luizdepra/hugo-coder/wiki/Multilingual-Mode)

See [`docs`](docs/home.md) folder.

## License


 docs/analytics.md

New file
@@ -0,0 +1 @@
WIP

 docs/comment-system.md

New file
@@ -0,0 +1 @@
WIP

 docs/configurations.md

New file
@@ -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.

 docs/contributing.md

New file
@@ -0,0 +1 @@
WIP

 docs/home.md

New file
@@ -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)



 docs/multilingual-mode.md

New file
@@ -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 <a href=\"{{ . }}\">homepage</a>."

[powered_by]
other = "Powered by"

[see_also]
other = "See also in"
```

 docs/quick-start.md

New file
@@ -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).