Skip to content

Commit 7c8367f

Browse files
luizdepraluizdepra
committed
Add docs folder with wiki content
1 parent 0a43cee commit 7c8367f

8 files changed

+464
-3
lines changed

‎README.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,9 @@ See [here](https://hugo-coder.netlify.app/).
2929
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.
3030
3. Build your site with `hugo server` and see the result at `http://localhost:1313/`.
3131

32-
## Extra Guides
33-
34-
* [Multilingual Mode](https://github.com/luizdepra/hugo-coder/wiki/Multilingual-Mode)
32+
## Documentations
3533

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

3736
## License
3837

‎docs/analytics.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
WIP

‎docs/comment-system.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
WIP

‎docs/configurations.md

+345
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
# Configurations
2+
3+
* [About Hugo Configurations](#about-hugo-configurations)
4+
* [Analytics](#analytics)
5+
* [Google Analytics](#google-analytics)
6+
* [Google Tag Manager](#google-tag-manager)
7+
* [Fathom Analytics](#fathom-analytics)
8+
* [Plausible Analytics](#plausible-analytics)
9+
* [Goat Counter](#goat-counter)
10+
* [Cloudflare](#cloudflare)
11+
* [Matomo](#matomo)
12+
* [Commenting Systems](#commenting-systems)
13+
* [Disqus](#disqus)
14+
* [Commento](#commento)
15+
* [Utterances](#utterances)
16+
* [Theme Parameters](#theme-parameters)
17+
* [Social Icons Configuration](#social-icons-configuration)
18+
* [Menu Items Configurations](#menu-items-configurations)
19+
* [CSP](#csp)
20+
* [Complete Example](#complete-example)
21+
* [Front Matter](#front-matter)
22+
* [Posts](#posts)
23+
24+
## About Hugo Configurations
25+
26+
This theme supports:
27+
28+
* Analytics
29+
* [Google Analytics](https://developers.google.com/analytics)
30+
* [Google Tag Manager](https://developers.google.com/tag-manager)
31+
* [Fathom Analytics](https://usefathom.com/)
32+
* [Plausible Analytics](https://plausible.io/)
33+
* [Goat Counter](https://www.goatcounter.com/)
34+
* [Cloudflare](https://www.cloudflare.com/analytics/)
35+
* [Matomo](https://matomo.org/)
36+
* Commenting Systems
37+
* [Disqus](https://disqus.com/)
38+
* [Commento](https://commento.io/)
39+
* [Utterances](https://utteranc.es/)
40+
41+
### Analytics
42+
43+
#### Google Analytics
44+
45+
Follow [these steps](https://gohugo.io/templates/internal/#configure-google-analytics).
46+
47+
#### Google Tag Manager
48+
49+
```toml
50+
[params.googleTagManager]
51+
id = "gid"
52+
```
53+
54+
#### Fathom Analytics
55+
56+
```toml
57+
[params.fathomAnalytics]
58+
siteID = "ABCDE"
59+
serverURL = "cdn.usefathom.com" # (optionnal) Replace if you use a custom domain
60+
```
61+
62+
#### Plausible Analytics
63+
64+
```toml
65+
[params.plausibleAnalytics]
66+
domain = "example.com"
67+
serverURL = "plausible.io" # (optionnal) Replace if you use a custom domain
68+
```
69+
70+
#### Goat Counter
71+
72+
```toml
73+
[params.goatCounter]
74+
code = "code" # You will access your account at https://[code].goatcounter.com
75+
```
76+
77+
#### Cloudflare
78+
79+
```toml
80+
[params.cloudflare]
81+
token = "token"
82+
```
83+
84+
#### Matomo
85+
86+
```toml
87+
[params.matomo]
88+
siteID = "ABCDE"
89+
serverURL = "analytics.example.com"
90+
```
91+
92+
### Commenting Systems
93+
94+
Comments are displayed within post pages, but can be disabled with `disableComments` front-matter.
95+
96+
#### Disqus
97+
98+
Follow [these steps](https://gohugo.io/content-management/comments/#configure-disqus).
99+
100+
#### Commento
101+
102+
```toml
103+
[params]
104+
commentoURL = "https://cdn.commento.io" # Replace if you use a custom domain
105+
```
106+
107+
#### Utterances
108+
109+
```toml
110+
[params.utterances]
111+
repo = "" # https://utteranc.es/#heading-repository
112+
issueTerm = "" # https://utteranc.es/#heading-mapping
113+
label = "" # https://utteranc.es/#heading-issue-label
114+
theme = "" # https://utteranc.es/#heading-theme
115+
```
116+
117+
## Theme Parameters
118+
119+
These are all the parameters used by `hugo-coder` theme.
120+
121+
| Name | Type | Required | Description | Default | Example |
122+
| ----------------------------- | ------ | -------- | ------------------------------------------------ | -------------------------------- | ------------------------------------------------ |
123+
| author | string | Yes | Author name. | | `"John Doe"` |
124+
| info | string | Yes | An headline, job title or similar. | | `"Full Stack Developer"` |
125+
| description | string | Yes | Description of the site. | | `"John Doe's personal website"` |
126+
| keywords | string | Yes | Site keywords. | | `"blog,developer,personal"` |
127+
| avatarURL | string | No | Photo of the author. | | `"images/avatar.jpg"` |
128+
| gravatar | string | No | Gravatar photo of the author | | `"[email protected]"` |
129+
| favicon_32 | string | No | Custom path to a 32x32 favicon. | `"/img/favicon-32x32.png"` | `"/img/favicon-32x32.png"` |
130+
| favicon_16 | string | No | Custom path to a 16x16 favicon. | `"/img/favicon-16x16.png"` | `"/img/favicon-16x16.png"` |
131+
| touchIcon | string | No | Custom path to a touch-icon | `"/images/apple-touch-icon.png"` | `"/images/apple-touch-icon.png"` |
132+
| since | string | No | Date shown in the footer before now year | | `"2020"` |
133+
| maxSeeAlsoItems | number | No | Series see also post count | `5` | `10` |
134+
| commit | string | No | Show the last git commit in the footer | | `"https://github.com/luizdepra/hugo-coder/tree/"`|
135+
| rtl | bool | No | Enable the Right To Left mode. | `false` | `true` or `false` |
136+
| math | bool | No | Enable MathJax Module and add JS into your site. | `false` | `true` or `false` |
137+
| katex | bool | No | Enable katex for all content types. | `false` | `true` or `false` |
138+
| colorScheme | string | No | Specify light/dark colorscheme | `"auto"` | `"auto"` or `"light"` or `"dark"` |
139+
| hideColorSchemeToggle | bool | No | If true, hides the color sheme toggle | `false` | `true` or `false` |
140+
| customCSS | list | No | Add extra CSS files to the website. | [] | `["css/extra-style.css"]` |
141+
| customSCSS | list | No | Add extra SCSS files to the website. | [] | `["scss/extra-style.scss"]` |
142+
| customJS | list | No | Add extra JS files to the website. | [] | `["js/extra-script.js"]` |
143+
| enableTwemoji | bool | No | Adds support for Twemoji | `false` | `true` or `false` |
144+
145+
### Social Icons Configuration
146+
147+
Social Icons are optional. To use them you will need to set at least all the following required parameters for each icon.
148+
149+
| Configuration | Type | Required | Description | Example |
150+
| -------------- | ------ | -------- | ---------------------------------------- | ------------------------------- |
151+
| name | string | Yes | Icon name. | `"Github"` |
152+
| icon | string | Yes | ForkAwesome icon classes. | `"fa fa-github"` |
153+
| weight | int | Yes | Icon order. | `1` |
154+
| url | string | Yes | URL to redirect. | `"https://github.com/johndoe/"` |
155+
156+
An example:
157+
158+
```toml
159+
[[params.social]]
160+
name = "Github"
161+
icon = "fa fa-github fa-2x"
162+
weight = 1
163+
url = "https://github.com/johndoe/"
164+
[[params.social]]
165+
name = "Gitlab"
166+
icon = "fa fa-gitlab fa-2x"
167+
weight = 2
168+
url = "https://gitlab.com/johndoe/"
169+
[[params.social]]
170+
name = "Twitter"
171+
icon = "fa fa-twitter fa-2x"
172+
weight = 3
173+
url = "https://twitter.com/johndoe/"
174+
```
175+
176+
### Menu Items Configurations
177+
178+
Menu Items are optional. To use them you will need to set all the following required parameters for each icon.
179+
180+
| Configuration | Type | Required | Description | Example |
181+
| -------------- | ------ | -------- | ---------------------------------------- | ------------------------------- |
182+
| name | string | Yes | Menu Item name. | `"Posts"` |
183+
| weight | int | Yes | Menu Item order. | `1` |
184+
| url | string | Yes | URL to redirect. | `"/posts/"` |
185+
| target | string | No | URL target attribute. | `"_blank"` |
186+
| rel | string | No | URL rel attribute. | `"alternate"` |
187+
| type | string | No | URL type attribute. | `"application/rss+xml"` |
188+
189+
An example:
190+
191+
```toml
192+
[[menu.main]]
193+
name = "Blog"
194+
weight = 1
195+
url = "posts/"
196+
[[menu.main]]
197+
name = "About"
198+
weight = 2
199+
url = "about/"
200+
```
201+
202+
### CSP
203+
204+
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.
205+
206+
| Configuration | Type | Required | Description | Example |
207+
| -------------- | ----------- | -------- | ----------- | ------------------------------- |
208+
| childsrc | string list | Yes | | `["'self'"]` |
209+
| fontsrc | string list | Yes | | `["'self'"]` |
210+
| formaction | string list | Yes | | `["'self'"]` |
211+
| framesrc | string list | Yes | | `["'self'"]` |
212+
| imgsrc | string list | Yes | | `["'self'"]` |
213+
| objectsrc | string list | Yes | | `["'self'"]` |
214+
| stylesrc | string list | Yes | | `["'self'"]` |
215+
| scriptsrc | string list | Yes | | `["'self'"]` |
216+
| prefetchsrc | string list | Yes | | `["'self'"]` |
217+
218+
An example:
219+
220+
```toml
221+
[params.csp]
222+
childsrc = ["'self'"]
223+
fontsrc = [
224+
"'self'",
225+
"https://fonts.gstatic.com",
226+
"https://cdn.jsdelivr.net/"
227+
]
228+
formaction = ["'self'"]
229+
framesrc = ["'self'"]
230+
imgsrc = ["'self'"]
231+
objectsrc = ["'none'"]
232+
stylesrc = [
233+
"'self'",
234+
"'unsafe-inline'",
235+
"https://fonts.googleapis.com/",
236+
"https://cdn.jsdelivr.net/"
237+
]
238+
scriptsrc = [
239+
"'self'",
240+
"'unsafe-inline'",
241+
"https://www.google-analytics.com"
242+
]
243+
prefetchsrc = ["'self'"]
244+
```
245+
246+
## Complete Example
247+
248+
This is a complete configuration example with some recommended values.
249+
250+
```toml
251+
baseurl = "http://www.example.com"
252+
title = "johndoe"
253+
theme = "hugo-coder"
254+
languagecode = "en"
255+
defaultcontentlanguage = "en"
256+
257+
paginate = 20
258+
259+
pygmentsstyle = "bw"
260+
pygmentscodefences = true
261+
pygmentscodefencesguesssyntax = true
262+
263+
disqusShortname = "yourdiscussshortname"
264+
265+
[params]
266+
author = "John Doe"
267+
info = "Full Stack DevOps and Magician"
268+
description = "John Doe's personal website"
269+
keywords = "blog,developer,personal"
270+
avatarurl = "images/avatar.jpg"
271+
#gravatar = "[email protected]"
272+
273+
favicon_32 = "/img/favicon-32x32.png"
274+
favicon_16 = "/img/favicon-16x16.png"
275+
276+
since = 2019
277+
278+
enableTwemoji = true
279+
280+
colorScheme = "auto"
281+
hidecolorschemetoggle = false
282+
283+
customCSS = ["css/custom.css"]
284+
customSCSS = ["scss/custom.scss"]
285+
customJS = ["js/custom.js"]
286+
287+
[taxonomies]
288+
category = "categories"
289+
series = "series"
290+
tag = "tags"
291+
author = "authors"
292+
293+
# Social links
294+
[[params.social]]
295+
name = "Github"
296+
icon = "fa fa-github fa-2x"
297+
weight = 1
298+
url = "https://github.com/johndoe/"
299+
[[params.social]]
300+
name = "Gitlab"
301+
icon = "fa fa-gitlab fa-2x"
302+
weight = 2
303+
url = "https://gitlab.com/johndoe/"
304+
[[params.social]]
305+
name = "Twitter"
306+
icon = "fa fa-twitter fa-2x"
307+
weight = 3
308+
url = "https://twitter.com/johndoe/"
309+
310+
# Menu links
311+
[[menu.main]]
312+
name = "Blog"
313+
weight = 1
314+
url = "posts/"
315+
[[menu.main]]
316+
name = "About"
317+
weight = 2
318+
url = "about/"
319+
```
320+
321+
## Front Matter
322+
323+
Hugo documentation: https://gohugo.io/content-management/front-matter
324+
325+
This theme includes one content type:
326+
327+
* [Posts](#posts), useful to display blog posts
328+
329+
### Posts
330+
331+
These are the front matter variables used by `hugo-coder` theme.
332+
333+
| Name | Type | Required | Description | Default | Example |
334+
| ---------------- | ------ | -------- | -------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
335+
| tags | list | No | Add tag(s) to this post. | | `["Hugo", "Go"]` |
336+
| categories | list | No | Add categorie(s) to this post. | | `["Hugo", "Go"]` |
337+
| series | list | No | Add series to this post (used by OpenGraph). | | `["Theme Demo"]` |
338+
| author | list | No | Add author to this post. | | `["John Doe"]` |
339+
| externalLink | string | No | Link to an external post. | | `"https://github.com/luizdepra/hugo-coder/wiki"` |
340+
| featuredImage | string | No | Link/path to add an image below post metadata. | | `"https://github.com/luizdepra/hugo-coder/blob/master/images/screenshot.png"` |
341+
| math | bool | No | If true, MathJax is enabled only for this post. | `false` | `true` or `false` |
342+
| katex | bool | No | If true, katex is enabled only for this post. | `false` | `true` or `false` |
343+
| disableComments | bool | No | If true, comments are disabled. | `false` | `true` or `false` |
344+
345+
> "tags", "categories", "series" and "authors" are taxonomies defined in the `config.toml` file.

‎docs/contributing.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
WIP

‎docs/home.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Welcome to the hugo-coder docs!
2+
3+
## Basic Usage
4+
5+
* [Quick Start](docs/quick-start.md)
6+
* [Configurations](docs/configurations.md)
7+
8+
## Extra Guides
9+
10+
* [Multilingual Mode](docs/multilingual-mode.md)
11+
* [Comment System](docs/comment-system.md)
12+
* [Analytics](docs/analytics.md)
13+
14+
## Maintainers & Developers
15+
16+
* [Contributing](docs/contributing.md)
17+
18+

0 commit comments

Comments
 (0)