Initial Commit

This commit is contained in:
Arsen Musayelyan 2021-10-24 02:25:31 -07:00
parent 71f901b3e3
commit 80ad96d0c4
283 changed files with 19733 additions and 0 deletions

6
archetypes/default.md Normal file
View File

@ -0,0 +1,6 @@
+++
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
+++

13
config.toml Normal file
View File

@ -0,0 +1,13 @@
baseURL = 'https://itd.arsenm.dev/'
languageCode = 'en-us'
title = 'ITD'
# Change the default theme to be use when building the site with Hugo
theme = "hugo-theme-relearn"
# For search functionality
[outputs]
home = [ "HTML", "RSS", "JSON"]
[params]
themeVariant = "blue"

25
content/_index.md Normal file
View File

@ -0,0 +1,25 @@
+++
title = "Home"
date = 2021-10-23T00:11:38-07:00
+++
# ITD
{{% notice warning %}}
There is currently a bug in the bluetooth library used for ITD that will cause the following error when using BlueZ 5.62+:
```
MapToStruct: Field not found: MTU
```
This is mentioned in [an issue](https://gitea.arsenm.dev/Arsen6331/infinitime/issues/3).
{{% /notice %}}
ITD is a daemon written in Go that communicates with the [InfinitTime](https://github.com/InfiniTimeOrg/InfiniTime) firmware running on the [PineTime](https://www.pine64.org/pinetime/) smartwatch.
ITD is meant to be fast and easy to use. As such, it is is only a single binary that works on all Linux systems since it is statically compiled and thus does not rely on any dynamic libraries.
ITD comes with `itctl`, a binary that uses the provided socket to control ITD and, by extension, the connected watch.
`itgui` is a gui frontend in ITD's repo. I do not compile it in CI as it requires OpenGL which makes cross-compiling a massive pain.

View File

@ -0,0 +1,12 @@
+++
chapter = true
pre = "<b>II. </b>"
title = "Configuration"
weight = 2
+++
### Chapter II
# Configuration
This chapter is about configuring ITD, including documentation about its config file and locations where it can be put.

View File

@ -0,0 +1,12 @@
+++
title = "About"
date = 2021-10-23T23:04:51-07:00
draft = true
weight = 1
+++
ITD has a config file. It's a TOML file that is, by default, at `/etc/itd.toml`. ITD will also search `~/.config/itd.toml` for a config and will choose the one in home if possible.
ITD can also be configured with environment variables. They take priority over the config. Variable names should be formatted as follows: ITD_&lt;config field&gt;. For example, socket path is `socket.path` in the config, so it would be `ITD_SOCKET_PATH` as an environment variable. To change which transliterators to use, `ITD_NOTIFS_TRANSLIT_USE` would be the variable, since the config field is `notifs.translit.use`.
In most cases, config edits come into effect immediately, and no restart of ITD is needed.

View File

@ -0,0 +1,105 @@
+++
title = "Sections"
date = 2021-10-23T23:04:51-07:00
draft = true
weight = 2
+++
This page is about the various sections in the config, their purpose, and how to use them.
### cfg.version
This field is temporary and was added because I changed the config format a while ago and wanted to make sure no one was still using the old config with a new version of ITD.
---
### socket
This section contains options for the control socket exposed by ITD.
#### path
This field is a string indicating the filepath at which the control socket should be opened.
---
### conn
The conn secton contains options for ITD's connection to the PineTime.
#### reconnect
This field is a boolean that dictates whether ITD will attempt to reconnect to the PineTime in case of a disconnect.
---
### on.connect
This section contains options for what happens when ITD first connects to a PineTime.
#### notify
This field is a boolean that dictates whether a notification should be sent to InfiniTime upon connection.
---
### on.reconnect
This section contains options for what happens when ITD reconnects to a PineTime after a disconnect.
#### notify
This field is a boolean that dictates whether a notification should be sent to InfiniTime upon reconnect.
#### setTime
This field is a boolean that dictates whether the time should be updated when ITD reconnects to InfiniTime.
---
### notifs.translit
#### use
This field is an array of strings which sets which transliterators should be used when transliterating text. The full list of transliterators can be found [here](https://gitea.arsenm.dev/Arsen6331/itd#transliteration) in the readme.
#### custom
This field is an array of strings which is a custom transliteration map. It can replace anything with something else. For example:
```toml
custom = [
"test", "replaced",
"æ", "ae",
"ē", "e",
]
```
An array is used because Golang does not preserve the order of a map.
---
### notifs.ignore
#### sender
This field is an array of strings which contains senders from which notifications are ignored.
#### summary
This field is an array of strings which contains notification summaries whose notifications will be ignored.
#### body&nbsp;
This field is an array of strings which contains notification bodies whose notifications will be ignored.
---
### music
This section contains options for music control
#### vol.interval
This field is an integer indicating how much the volume should be changed for each volume up or down event from the music control app.

View File

@ -0,0 +1,12 @@
+++
chapter = true
pre = "<b>I. </b>"
title = "Getting Started"
weight = 1
+++
### Chapter I
# Getting Started
This chapter is about `itd`, its purpose, and what it does. It also includes a note about my age and ability to respond.

View File

@ -0,0 +1,37 @@
+++
title = "Features"
date = 2021-10-23T23:04:51-07:00
draft = true
weight = 2
+++
The list of features is mentioned [here](https://gitea.arsenm.dev/Arsen6331/itd#features) in the readme. This page will describe how certain features work and how new ones are added.
### Notification Relay
The notification relay works by listening for method calls on the `org.freedesktop.Notifications` DBus interface. Any such method call represents a notification being sent. ITD reads the data from the method call and creates a notification suitable for ANS (Alert Notification Service) which is used by InfniTime to display notifications. This means DBus must be installed and running for ITD to relay notifications.
### Transliteration
Transliteration for ITD is implemented in a custom `translit` package. It consists of a `Transliterator` interface which looks like this:
```go
type Transliterator interface {
Transliterate(string) string
Init()
}
```
Anything that satisfies that interface can be added to the `Transliterators` map and then used in ITD's config in the `notifs.translit.use` array.
### Music Control
Music control is implemented using `playerctl` which uses the MPRIS DBus interface. This means it will work with any music player which supports MPRIS. `playerctl` must be installed for ITD to do music control.
### Control Socket
ITD exposes a UNIX socket at `/tmp/itd/socket` by default. This socket can be used to control the daemon. It is how `itctl` and `itgui` work. This can be used in any language which supports UNIX sockets which is nearly all of them. Even bash can be used with `netcat`.
### New Features
New features are added whenever I find out they exist from InfiniTime's repo or developers. This means ITD's master branch may contain features not yet released in InfiniTime.

View File

@ -0,0 +1,15 @@
+++
title = "Note"
date = 2021-10-23T22:55:22-07:00
draft = true
weight = 3
+++
This is a note for anyone using or planning to contribute to ITD. I am {{<raw>}}<span id="age">Loading...</span>{{</raw>}} years old and, at times, may be busy with school and unable to answer questions and/or work on the project for a while. If you do not get an answer quickly, I am probably busy. However, I sometimes answer questions, comment on issues, or push code while in school. That means there may be pauses where I cannot answer questions or comment on issues because I am moving between classes or busy doing an assignment. Please do not bombard me with messages if this occurs, I will answer as soon as I can.
{{<raw>}}
<script>
birthday = new Date("April 24, 2005")
document.getElementById("age").innerHTML = (new Date).getFullYear() - birthday.getFullYear()
</script>
{{</raw>}}

View File

@ -0,0 +1,10 @@
+++
title = "Purpose"
date = 2021-10-23T22:34:32-07:00
draft = true
weight = 1
+++
ITD was created because I could not find a good InfiniTime companion for Linux. There is [Siglo](https://github.com/alexr4535/siglo) which cannot do much beyond syncing time and updating the watch and is not very reliable. There is [Amazfish](https://github.com/piggz/harbour-amazfish) which works, but at least for me, is a bit clunky and unreliable.
I wanted something that was easy enough to use that I could just run it and forget about it, and had any feature I may want to use. Also, I needed it to work on Linux because I only own Linux devices, including my phone, which is a PinePhone. This leads to the next requirement. I needed it to be easily cross-compiled so that I could use it on all my computers as well as aarch64 devices such as my PinePhone and Raspberry Pi 4s. All of these reasons contributed to me deciding to make ITD and they are what I try to emphasize.

338
content/socket/API.md Normal file
View File

@ -0,0 +1,338 @@
+++
title = "API"
date = 2021-10-23T23:04:51-07:00
draft = true
weight = 2
+++
This page documents the API of ITD's control socket.
## Request format
Request sent to ITD's socket should be valid JSON with the following format:
| Field | Type |
|-------|------|
| type | int |
| data | any |
Example:
```json
{"type": 5, "data": {"title": "title1", "body": "body1"}}
```
Sends notification titled "title1" with a body "body1".
---
## Response format
Responses received from ITD will be valid JSON and have the following format:
| Field | Type |
|--------|--------|
| type | int |
| value? | any |
| msg? | string |
| id? | string |
| error | bool |
(Fields marked with "?" may not exist in all responses)
Examples:
```json
{"type":1,"value":66,"error":false}
```
```json
{"type":6,"msg":"Data required for settime request","error":true}
```
```json
{"type":6,"error":false}
```
---
## Requests
This section will document each request type, its response, and what data it needs.
### Heart Rate
The heart rate request's type is 0. It requires no data and returns a `uint8` in its value field.
Example request:
```json
{"type":0}
```
Example response:
```json
{"type":0,"value":92,"error":false}
```
---
### Battery Level
The battery level request's type is 1. It requires no data and returns a `uint8` in its value field.
Example request:
```json
{"type":1}
```
Example response:
```json
{"type":1,"value":65,"error":false}
```
---
### Firmware Version
The firmware version request's type is 2. It requires no data and returns a string in its value field.
Example request:
```json
{"type":2}
```
Example response:
```json
{"type":2,"value":"1.6.0","error":false}
```
---
### Firmware Upgrade
The firmware upgrade request's type is 3. It requires data in the following format:
| Field | Type |
|-------|----------|
| type | int |
| files | []string |
Example requests:
```json
{"type": 3, "data": {"type": 0, "files": ["pinetime-mcuboot-app-dfu-1.6.0.zip"]}}
```
```json
{"type": 3, "data": {"type": 1, "files": ["pinetime-mcuboot-app-image-1.6.0.bin", "pinetime-mcuboot-app-image-1.6.0.dat"]}}
```
The paths need to be absolute. They are not absolute here as this is an example.
Example response:
```json
{"type":3,"value":{"sent":2800,"recvd":2800,"total":361152},"error":false}
```
Responses will be sent continuously until the transfer is complete.
---
### Bluetooth Address
The bluetooth address request's type is 4. It requires no data and returns a string in its value field.
Example request:
```json
{"type":4}
```
Example response:
```json
{"type":4,"value":"ED:47:AC:47:F4:FB","error":false}
```
---
### Notify
The notify request's type is 5. It reques data in the following format:
| Field | Type |
|-------|--------|
| title | string |
| body | string |
Example request:
```json
{"type": 5, "data": {"title": "title1", "body": "body1"}}
```
Example response:
```json
{"type":5,"error":false}
```
---
### Set Time
The set time request's type is 6. It requires a string as data. The string must be a date and time formatted as ISO8601/RFC3339 or the string "now".
Example requests:
```json
{"type":6,"data":"2021-10-24T06:40:35-07:00"}
```
```json
{"type":6,"data":"now"}
```
Example response:
```json
{"type":6,"error":false}
```
---
### Watch Heart Rate
The watch heart rate request's type is 7. It requires no data. It returns a uint8 as its value every time the heart rate changes until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
```json
{"type":7}
```
Example response:
```json
{"type":7,"value":83,"id":"d12e2ec2-accd-400c-9da7-be86580b067f","error":false}
```
---
### Watch Battery Level
The watch battery level request's type is 8. It requires no data. It returns a uint8 as its value every time the battery level changes until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
```json
{"type":8}
```
Example response:
```json
{"type":8,"value":63,"id":"70cce449-d8b8-4e07-a000-0ca4ee7a9c42","error":false}
```
---
### Motion
The motion request's type is 9. It requires no data. It returns data in the following format:
| Field | Type |
|-------|--------|
| X | 1nt16 |
| Y | 1nt16 |
| Z | 1nt16 |
The values will only update if the watch is not sleeping.
Example request:
```json
{"type":9}
```
Example response:
```json
{"type":9,"value":{"X":-220,"Y":475,"Z":-893},"error":false}
```
---
### Watch Motion
The watch motion request's type is 10. It requires no data. It returns the same data as the motion request as its value every time the watch moves until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
```json
{"type":10}
```
Example response:
```json
{"type":10,"value":{"X":-220,"Y":475,"Z":-893},"id":"d084789d-9fdc-4fce-878b-4408cd616901","error":false}
```
---
### Step Count
The step count request's type is 11. It requires no data and returns a `uint32` in its value field.
Example request:
```json
{"type":11}
```
Example response:
```json
{"type":11,"value":1043,"error":false}
```
---
### Watch Step Count
The watch step count request's type is 12. It requires no data. It returns a `uint32` in its value field every time the step count changes until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
```json
{"type":12}
```
Example response:
```json
{"type":12,"value":1045,"id":"54583e8f-80f6-45e3-a97f-b111defc0edc","error":false}
```
---
### Cancel
The cancel request's type is 13. It requires a string as data, containing the ID returned by a watch request. Once run, it will terminate the watch request, clean up anything it was using, and cause ITD to stop listening for its value from the watch.
Example request:
```json
{"type":13,"data":"54583e8f-80f6-45e3-a97f-b111defc0edc"}
```
Example response:
```json
{"type":13,"error":false}
```

12
content/socket/_index.md Normal file
View File

@ -0,0 +1,12 @@
+++
chapter = true
pre = "<b>III. </b>"
title = "Socket"
weight = 3
+++
### Chapter III
# Socket
This chapter will document the API of the control socket exposed by ITD.

33
content/socket/types.md Normal file
View File

@ -0,0 +1,33 @@
+++
title = "Types"
date = 2021-10-23T23:04:51-07:00
draft = true
weight = 1
+++
When making a request to ITD or receiving a response from it, a type integer is used to indicate what kind of request is being made. This page will document the integers and what they mean.
Here is a list of all the request types:
```go
const (
ReqTypeHeartRate = 0
ReqTypeBattLevel = 1
ReqTypeFwVersion = 2
ReqTypeFwUpgrade = 3
ReqTypeBtAddress = 4
ReqTypeNotify = 5
ReqTypeSetTime = 6
ReqTypeWatchHeartRate = 7
ReqTypeWatchBattLevel = 8
ReqTypeMotion = 9
ReqTypeWatchMotion = 10
ReqTypeStepCount = 11
ReqTypeWatchStepCount = 12
ReqTypeCancel = 13
)
```
The response types are always the same as the request type used.
ITD uses Go's `iota` keyword to generate these numbers, but I have placed their actual values on this page to make it easier to use them in other languages.

View File

@ -0,0 +1 @@
<span style="font-size: 24pt;">ITD</span>

View File

@ -0,0 +1 @@
{{.Inner}}

View File

@ -0,0 +1,16 @@
# https://editorconfig.org
root = true
[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
trim_trailing_whitespace = true
[*.js]
insert_final_newline = true
[*.md]
trim_trailing_whitespace = false

View File

@ -0,0 +1,14 @@
name: Build site
description: Builds the Hugo exampleSite for later deploy on GitHub-Pages
runs:
using: composite
steps:
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: 'latest'
- name: Build site
shell: bash
run: |
hugo --minify --source ${GITHUB_WORKSPACE}/exampleSite --destination ${GITHUB_WORKSPACE}/../public --cleanDestinationDir --gc --baseURL https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/ --theme ${GITHUB_WORKSPACE}

View File

@ -0,0 +1,73 @@
name: Check milestone
description: Checks if the given milestone and its according tag are valid to be released
inputs:
milestone:
description: Milestone for this release
required: true
github_token:
description: Secret GitHub token
required: true
outputs:
outcome:
description: Result of the check, success or failure
value: ${{ steps.outcome.outputs.outcome }}
runs:
using: composite
steps:
- name: Get tag uniqueness
id: unique_tag
uses: mukunku/tag-exists-action@v1.0.0
with:
tag: ${{ env.MILESTONE }}
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
- name: Get closed issues for milestone
id: closed_issues
uses: octokit/graphql-action@v2.x
with:
query: |
query {
search(first: 1, type: ISSUE, query: "user:${{ github.repository_owner }} repo:${{ github.event.repository.name }} milestone:${{ env.MILESTONE }} state:closed") {
issueCount
}
}
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
- name: Get open issues for milestone
id: open_issues
uses: octokit/graphql-action@v2.x
with:
query: |
query {
search(first: 1, type: ISSUE, query: "user:${{ github.repository_owner }} repo:${{ github.event.repository.name }} milestone:${{ env.MILESTONE }} state:open") {
issueCount
}
}
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
- name: Set outcome
id: outcome
shell: bash
run: |
if [ "${{ fromJSON(steps.closed_issues.outputs.data).search.issueCount > 0 && fromJSON(steps.open_issues.outputs.data).search.issueCount == 0 && steps.unique_tag.outputs.exists == 'false' }}" = "true" ]; then
echo "::set-output name=outcome::success"
else
echo "::set-output name=outcome::failure"
fi
- name: Log results and exit
shell: bash
run: |
echo outcome : ${{ steps.outcome.outputs.outcome }}
echo has unique tag : ${{ steps.unique_tag.outputs.exists == 'false' }}
echo has closed issues: ${{ fromJSON(steps.closed_issues.outputs.data).search.issueCount > 0 }}
echo has open issues : ${{ fromJSON(steps.open_issues.outputs.data).search.issueCount > 0 }}
if [ "${{ steps.outcome.outputs.outcome }}" = "failure" ]; then
exit 1
fi

View File

@ -0,0 +1,17 @@
name: Deploy site
description: Deploys a built site on GitHub-Pages
inputs:
github_token:
description: Secret GitHub token
required: true
runs:
using: composite
steps:
- name: Deploy site
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ env.GITHUB_TOKEN }}
publish_dir: ${{ env.GITHUB_WORKSPACE }}/../public
env:
GITHUB_TOKEN: ${{ inputs.github_token }}
GITHUB_WORKSPACE: ${{ github.workspace }}

View File

@ -0,0 +1,64 @@
name: Release milestone
description: Creates a release with changelog and tag out of a given milestone
inputs:
milestone:
description: Milestone for this release
required: true
github_token:
description: Secret GitHub token
required: true
runs:
using: composite
steps:
- name: Setup node
uses: actions/setup-node@v2
with:
node-version: '16'
- name: Close milestone
uses: Akkjon/close-milestone@v2
with:
milestone_name: ${{ env.MILESTONE }}
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
- name: Create provisionary tag
shell: bash
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
run: |
git config user.name "GitHub Actions Bot"
git config user.email "<>"
git tag --message "" "$MILESTONE"
git push origin "$MILESTONE"
- name: Update changelog
shell: bash
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
GREN_GITHUB_TOKEN: ${{ inputs.github_token }}
run: |
npx github-release-notes@0.17.1 changelog --generate --override --tags=all
git add *
git commit --message "Ship tag $MILESTONE"
git push origin main
- name: Create final tag
shell: bash
env:
MILESTONE: ${{ inputs.milestone }}
GITHUB_TOKEN: ${{ inputs.github_token }}
run: |
git tag --force --message "" "$MILESTONE"
git push --force origin "$MILESTONE"
- name: Publish release
shell: bash
env:
MILESTONE: ${{ inputs.milestone }}
GREN_GITHUB_TOKEN: ${{ inputs.github_token }}
run: |
npx github-release-notes@0.17.1 release --tags "$MILESTONE"

View File

@ -0,0 +1,28 @@
# Guidelines
## For Development
- help us putting your code into production by opening a meaningful issue
- stay simple for the user by focusing on the mantra "convention over configuration"
- at installation the site should work reasonable without (m)any configuration
- stay close to the Hugo way
- don't use npm or any preprocessing, our contributors may not be front-end developers
- document new features in exampleSite
- don't break existing features if you don't have to
- remove reported issue from the browser's console
- be compatible to IE11, at least for main functionality, for Javascript this means:
- test in IE11
- check caniuse.com
- don't use arrow functions
- don't use template literals
- don't use other fancy new ES5/6 stuff
## For Release
- create releases following [semver policy](https://semver.org/)
- we are using GitHub actions to create new releases
- a release is based on a milestone named like the release itself - just the version number, eg: 1.1.0
- remember that there have to be at least one closed issue assigned to the milestone
- the release action only runs successfully if all assigned issues for this milestone are closed
- the milestone itself will be closed during execution of the action
- a once released milestone can not be released again

View File

@ -0,0 +1,20 @@
name: Build
on:
push: # Build on all pushes but only deploy for main branch
pull_request: # Build on all PRs regardless what branch
workflow_dispatch: # Allow this task to be manually started (you'll never know)
jobs:
ci:
name: Run build
runs-on: ubuntu-latest
if: github.event_name != 'push' || (github.event_name == 'push' && github.ref != 'refs/heads/main')
steps:
- name: Checkout repo
uses: actions/checkout@v2
with:
submodules: true # Fetch Hugo themes (true OR recursive)
- name: Build site
uses: ./.github/actions/build_site

View File

@ -0,0 +1,25 @@
name: Deploy
on:
push: # Build on all pushes but only deploy for main branch
workflow_dispatch: # Allow this task to be manually started (you'll never know)
jobs:
deploy:
name: Run deploy
runs-on: ubuntu-latest
if: github.event_name != 'push' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
steps:
- name: Checkout repo
uses: actions/checkout@v2
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Build site
uses: ./.github/actions/build_site
- name: Deploy site
uses: ./.github/actions/deploy_site
with:
github_token: ${{ secrets.GITHUB_TOKEN }}

View File

@ -0,0 +1,42 @@
name: Release
on:
workflow_dispatch:
inputs:
milestone:
description: 'Milestone for this release'
required: true
jobs:
release:
name: Run release
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Check milestone
id: check
uses: ./.github/actions/check_milestone
with:
milestone: ${{ github.event.inputs.milestone }}
github_token: ${{ secrets.GITHUB_TOKEN }}
- name: Create release
if: ${{ steps.check.outputs.outcome == 'success' }}
uses: ./.github/actions/release_milestone
with:
milestone: ${{ github.event.inputs.milestone }}
github_token: ${{ secrets.GITHUB_TOKEN }}
# We need to deploy the site again to show the updated changelog
- name: Build site
uses: ./.github/actions/build_site
- name: Deploy site
uses: ./.github/actions/deploy_site
with:
github_token: ${{ secrets.GITHUB_TOKEN }}

4
themes/hugo-theme-relearn/.gitignore vendored Normal file
View File

@ -0,0 +1,4 @@
.DS_Store
public/
exampleSite/public
exampleSite/hugo*.exe

View File

@ -0,0 +1,36 @@
module.exports = {
changelogFilename: "exampleSite/content/basics/CHANGELOG.md",
dataSource: "milestones",
groupBy: {
"Enhancements": [
"feature",
],
"Fixes": [
"bug"
],
"Maintenance": [
"task",
],
"Uncategorised": [
"closed",
],
},
ignoreLabels: [
"discussion",
"documentation",
"duplicate",
"hugo",
"invalid",
"support",
"wontfix",
],
ignoreTagsWith: [
"Relearn",
],
milestoneMatch: "{{tag_name}}",
onlyMilestones: true,
template: {
group: "\n### {{heading}}\n",
release: ({ body, date, release }) => `## ${release} (` + date.replace( /(\d+)\/(\d+)\/(\d+)/, '$3-$2-$1' ) + `)\n${body}`,
},
};

View File

@ -0,0 +1,23 @@
The MIT License (MIT)
Copyright (c) 2021 Sören Weber
Copyright (c) 2017 Valere JEANTET
Copyright (c) 2016 MATHIEU CORNIC
Copyright (c) 2014 Grav
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

View File

@ -0,0 +1,52 @@
# Hugo Relearn Theme
A theme for [Hugo](https://gohugo.io/) designed for documentation.
![Overview](https://github.com/McShelby/hugo-theme-relearn/raw/main/images/screenshot.png)
## Motivation
The theme initially was a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for the Learn theme.
## Main features
- Automatic Search
- Multilingual mode
- Unlimited menu levels
- Automatic next/prev buttons to navigate through menu entries
- Image resizing, shadow…
- Attachments files
- List child pages
- Mermaid diagram (flowchart, sequence, gantt)
- Customizable look and feel and theme variants
- Buttons
- Tip/Note/Info/Warning boxes
- Expand
- Tabs
- File inclusion
## Installation
Visit the [installation instructions](https://mcshelby.github.io/hugo-theme-relearn/basics/installation) to learn how to setup the theme in your Hugo installation.
## Usage
Visit the [documentation](https://mcshelby.github.io/hugo-theme-relearn/) to learn about all available features and how to use them.
## Changelog
See the [changelog](https://mcshelby.github.io/hugo-theme-relearn/basics/history) for a complete list of releases.
## Contribution
You are most welcome to contribute to the source code but please visit the [contribution guidelines](https://github.com/McShelby/hugo-theme-relearn/blob/main/.github/contributing.md) first.
## License
This theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE).
## Credits
Special thanks to [everyone who has contributed](https://github.com/McShelby/hugo-theme-relearn/graphs/contributors) to this project.
Many thanks to [@matcornic](https://github.com/matcornic) for his work on the [Learn theme](https://github.com/matcornic/hugo-theme-learn).

View File

@ -0,0 +1,12 @@
+++
chapter = true
pre = "<b>X. </b>"
title = "{{ replace .Name "-" " " | title }}"
weight = 5
+++
### Chapter X
# Some Chapter title
Lorem Ipsum.

View File

@ -0,0 +1,6 @@
+++
title = "{{ replace .Name "-" " " | title }}"
weight = 5
+++
Lorem Ipsum.

View File

@ -0,0 +1,106 @@
baseURL = "https://example.com"
canonifyURLs = true
languageCode = "en"
defaultContentLanguage = "en"
title = "Hugo Relearn Documentation"
theme = "hugo-theme-relearn"
themesdir = "../.."
relativeURLs = true
[params]
editURL = "https://github.com/McShelby/hugo-theme-relearn/edit/main/exampleSite/content/"
description = "Documentation for Hugo Relearn Theme"
author = "Sören Weber"
showVisitedLinks = true
disableBreadcrumb = false
disableNextPrev = false
disableLandingPageButton = true
disableMermaid = false
titleSeparator = "::"
themeVariant = "relearn"
disableSeoHiddenPages = true
[outputs]
home = ["HTML", "RSS", "JSON"] # add JSON to the home page to support lunr search
[markup]
[markup.highlight]
style = "base16-snazzy" # choose a color theme or create your own
guessSyntax = false # if set to true, avoid unstyled code if no language was given but mermaid code fences will not work anymore
[markup.goldmark.renderer]
unsafe= true
[module]
[module.hugoVersion]
min = "0.25"
[Languages]
[Languages.en]
title = "Documentation for Hugo Relearn Theme"
weight = 1
languageName = "English"
landingPageURL = "/"
landingPageName = "<i class='fas fa-home'></i> Home"
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-tags'></i> Tags"
url = "/tags/"
weight = 5
[[Languages.en.menu.shortcuts]]
name = "<i class='fab fa-fw fa-github'></i> GitHub repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
weight = 10
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-camera'></i> Showcases"
url = "/showcase/"
weight = 11
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-bookmark'></i> Hugo Documentation"
identifier = "hugodoc"
url = "https://gohugo.io/"
weight = 20
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-bullhorn'></i> Credits"
url = "/credits/"
weight = 30
[Languages.pir]
title = "Documentat'n fer Cap'n Hugo Relearrrn Theme"
weight = 1
languageName = "Arrr! Pirrrates"
landingPageURL = "/pir/"
landingPageName = "<i class='fas fa-home'></i> Arrr! Home"
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-fw fa-tags'></i> Arrr! Tags"
url = "/tags/"
weight = 5
[[Languages.pir.menu.shortcuts]]
name = "<i class='fab fa-fw fa-github'></i> GitHub repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
weight = 10
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-fw fa-camera'></i> Showcases"
url = "/showcase/"
weight = 11
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-fw fa-bookmark'></i> Cap'n Hugo Documentat'n"
identifier = "hugodoc"
url = "https://gohugo.io/"
weight = 20
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-fw fa-bullhorn'></i> Crrredits"
url = "/credits/"
weight = 30

View File

@ -0,0 +1,52 @@
+++
title = "Relearn Theme for Hugo"
+++
# Hugo Relearn Theme
The [Relearn theme](http://github.com/McShelby/hugo-theme-relearn) is a theme for [Hugo](https://gohugo.io/), a static website generator written in Go. Where Hugo is often used for blogs, this theme is designed with documentation in mind.
{{% notice info %}}
The theme initially was a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for Learn theme.
{{% /notice %}}
## Main features
{{% notice tip %}}
See [what's new]({{% relref "basics/migration" %}}) within the latest update.
{{% /notice %}}
* [Automatic Search]({{%relref "basics/configuration/_index.md#activate-search" %}})
* [Multilingual mode]({{%relref "cont/i18n" %}})
* Unlimited menu levels
* Automatic next/prev buttons to navigate through menu entries
* [Image resizing, shadow...]({{%relref "cont/markdown#images" %}})
* [Attachments files]({{%relref "shortcodes/attachments" %}})
* [List child pages]({{%relref "shortcodes/children" %}})
* [Mermaid diagram]({{%relref "shortcodes/mermaid" %}}) (flowchart, sequence, gantt)
* [Customizable look and feel and theme variants]({{%relref "basics/customization"%}})
* [Buttons]({{%relref "shortcodes/button" %}})
* [Tip/Note/Info/Warning boxes]({{%relref "shortcodes/notice" %}})
* [Expand]({{%relref "shortcodes/expand" %}})
* [Tabs]({{%relref "shortcodes/tabs" %}})
* [File inclusion]({{%relref "shortcodes/include" %}})
![Screenshot](https://github.com/McShelby/hugo-theme-relearn/raw/main/images/screenshot.png?width=40pc&classes=shadow)
## Getting support
To get support, feel free to open a new [discussion topic](https://github.com/McShelby/hugo-theme-relearn/discussions) or [issue](https://github.com/McShelby/hugo-theme-relearn/issues) in the official repository on GitHub.
## Become a contributor
Feel free to update this documentation by just clicking the **Edit this page** link displayed on top right of each page. Your changes will be deployed automatically once they were reviewed.
You are most welcome to contribute bugfixes or even new features to the source code by making pull requests to the [official repository](https://github.com/McShelby/hugo-theme-relearn) via GitHub. Please visit the [contribution guidelines](https://github.com/McShelby/hugo-theme-relearn/blob/main/.github/contributing.md) first.
## License
This theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE).
## Credits
This theme would not be possible without the work of many others. See the [credits]({{%relref "credits" %}}) for a detailed list.

View File

@ -0,0 +1,4 @@
+++
title = "Relearrrn Theme fer Cap'n Hugo"
+++
{{< piratify >}}

View File

@ -0,0 +1,228 @@
# Changelog
## 2.6.0 (2021-10-21)
### Fixes
- [**bug**] theme: generate correct links if theme served from subdirectory [#120](https://github.com/McShelby/hugo-theme-relearn/issues/120)
+++
## 2.5.1 (2021-10-12)
### Fixes
- [**bug**] security: fix XSS for malicioius image URLs [#117](https://github.com/McShelby/hugo-theme-relearn/issues/117)
+++
## 2.5.0 (2021-10-08)
### Enhancements
- [**feature**] syntax highlight: provide default colors for unknown languages [#113](https://github.com/McShelby/hugo-theme-relearn/issues/113)
### Fixes
- [**bug**] security: fix XSS for malicioius URLs [#114](https://github.com/McShelby/hugo-theme-relearn/issues/114)
- [**bug**] menu: write correct local shortcut links [#112](https://github.com/McShelby/hugo-theme-relearn/issues/112)
+++
## 2.4.1 (2021-10-07)
### Fixes
- [**bug**] theme: remove runtime styles from print [#111](https://github.com/McShelby/hugo-theme-relearn/issues/111)
+++
## 2.4.0 (2021-10-07)
### Enhancements
- [**feature**] lang: add vietnamese translation [#109](https://github.com/McShelby/hugo-theme-relearn/issues/109)
- [**feature**] theme: simplify stylesheet for color variants [#107](https://github.com/McShelby/hugo-theme-relearn/issues/107)
- [**feature**] hidden pages: remove from RSS feed, JSON, taxonomy etc [#102](https://github.com/McShelby/hugo-theme-relearn/issues/102)
- [**feature**] theme: announce alternative content in header [#101](https://github.com/McShelby/hugo-theme-relearn/issues/101)
- [**feature**] menu: frontmatter option to change sort predicate [#98](https://github.com/McShelby/hugo-theme-relearn/issues/98)
- [**feature**] menu: add default setting for menu expansion [#97](https://github.com/McShelby/hugo-theme-relearn/issues/97)
- [**feature**] theme: improve print style [#93](https://github.com/McShelby/hugo-theme-relearn/issues/93)
- [**feature**] theme: improve style [#92](https://github.com/McShelby/hugo-theme-relearn/issues/92)
### Fixes
- [**bug**] include: don't generate additional HTML if file should be displayed "as is" [#110](https://github.com/McShelby/hugo-theme-relearn/issues/110)
- [**bug**] attachments: fix broken links if multilang config is used [#105](https://github.com/McShelby/hugo-theme-relearn/issues/105)
- [**bug**] theme: fix sticky header to remove horizontal scrollbar [#82](https://github.com/McShelby/hugo-theme-relearn/issues/82)
### Maintenance
- [**task**] chore: update fontawesome [#94](https://github.com/McShelby/hugo-theme-relearn/issues/94)
+++
## 2.3.2 (2021-09-20)
### Fixes
- [**bug**] docs: rename history pirate translation [#91](https://github.com/McShelby/hugo-theme-relearn/issues/91)
+++
## 2.3.1 (2021-09-20)
### Fixes
- [**bug**] docs: rename english pirate translation to avoid crash on rendering [#90](https://github.com/McShelby/hugo-theme-relearn/issues/90)
+++
## 2.3.0 (2021-09-13)
### Fixes
- [**bug**] theme: fix usage of section element [#88](https://github.com/McShelby/hugo-theme-relearn/issues/88)
### Maintenance
- [**task**] theme: ensure IE11 compatiblity [#89](https://github.com/McShelby/hugo-theme-relearn/issues/89)
- [**task**] docs: Arrr! showcase multilang featurrre [#87](https://github.com/McShelby/hugo-theme-relearn/issues/87)
+++
## 2.2.0 (2021-09-09)
### Enhancements
- [**feature**] sitemap: hide hidden pages from sitemap and SEO indexing [#85](https://github.com/McShelby/hugo-theme-relearn/issues/85)
### Fixes
- [**bug**] theme: fix showVisitedLinks in case Hugo is configured to modify relative URLs [#86](https://github.com/McShelby/hugo-theme-relearn/issues/86)
### Maintenance
- [**task**] theme: switch from data-vocabulary to schema [#84](https://github.com/McShelby/hugo-theme-relearn/issues/84)
+++
## 2.1.0 (2021-09-07)
### Enhancements
- [**feature**] search: open expand if it contains search term [#80](https://github.com/McShelby/hugo-theme-relearn/issues/80)
- [**feature**] menu: scroll active item into view [#79](https://github.com/McShelby/hugo-theme-relearn/issues/79)
- [**feature**] search: disable search in hidden pages [#76](https://github.com/McShelby/hugo-theme-relearn/issues/76)
- [**feature**] search: improve readablility of index.json [#75](https://github.com/McShelby/hugo-theme-relearn/issues/75)
- [**feature**] search: increase performance [#74](https://github.com/McShelby/hugo-theme-relearn/issues/74)
- [**feature**] search: improve search context preview [#73](https://github.com/McShelby/hugo-theme-relearn/issues/73)
### Fixes
- [**bug**] search: hide non-site content [#81](https://github.com/McShelby/hugo-theme-relearn/issues/81)
- [**bug**] menu: always hide hidden sub pages [#77](https://github.com/McShelby/hugo-theme-relearn/issues/77)
+++
## 2.0.0 (2021-08-28)
### Enhancements
- [**feature**] tabs: enhance styling [#65](https://github.com/McShelby/hugo-theme-relearn/issues/65)
- [**feature**] theme: improve readability [#64](https://github.com/McShelby/hugo-theme-relearn/issues/64)
- [**feature**] menu: show hidden pages if accessed directly [#60](https://github.com/McShelby/hugo-theme-relearn/issues/60)
- [**feature**] theme: treat pages without title as hidden [#59](https://github.com/McShelby/hugo-theme-relearn/issues/59)
- [**feature**] search: show search results if field gains focus [#58](https://github.com/McShelby/hugo-theme-relearn/issues/58)
- [**feature**] theme: add partial templates for pre/post menu entries [#56](https://github.com/McShelby/hugo-theme-relearn/issues/56)
- [**feature**] theme: make chapter archetype more readable [#55](https://github.com/McShelby/hugo-theme-relearn/issues/55)
- [**feature**] children: add parameter for container style [#53](https://github.com/McShelby/hugo-theme-relearn/issues/53)
- [**feature**] theme: make content a template [#50](https://github.com/McShelby/hugo-theme-relearn/issues/50)
- [**feature**] menu: control menu expansion with alwaysopen parameter [#49](https://github.com/McShelby/hugo-theme-relearn/issues/49)
- [**feature**] include: new shortcode to include other files [#43](https://github.com/McShelby/hugo-theme-relearn/issues/43)
- [**feature**] theme: adjust print styles [#35](https://github.com/McShelby/hugo-theme-relearn/issues/35)
- [**feature**] code highligher: switch to standard hugo highlighter [#32](https://github.com/McShelby/hugo-theme-relearn/issues/32)
### Fixes
- [**bug**] arrow-nav: default sorting ignores ordersectionsby [#63](https://github.com/McShelby/hugo-theme-relearn/issues/63)
- [**bug**] children: default sorting ignores ordersectionsby [#62](https://github.com/McShelby/hugo-theme-relearn/issues/62)
- [**bug**] arrow-nav: fix broken links on (and below) hidden pages [#61](https://github.com/McShelby/hugo-theme-relearn/issues/61)
- [**bug**] theme: remove superflous singular taxonomy from taxonomy title [#46](https://github.com/McShelby/hugo-theme-relearn/issues/46)
- [**bug**] theme: missing --MENU-HOME-LINK-HOVER-color in documentation [#45](https://github.com/McShelby/hugo-theme-relearn/issues/45)
- [**bug**] theme: fix home link when base URL has some path [#44](https://github.com/McShelby/hugo-theme-relearn/issues/44)
### Maintenance
- [**task**] docs: include changelog in exampleSite [#33](https://github.com/McShelby/hugo-theme-relearn/issues/33)
+++
## 1.2.0 (2021-07-26)
### Enhancements
- [**feature**] theme: adjust copy-to-clipboard [#29](https://github.com/McShelby/hugo-theme-relearn/issues/29)
- [**feature**] attachments: adjust style between notice boxes and attachments [#28](https://github.com/McShelby/hugo-theme-relearn/issues/28)
- [**feature**] theme: adjust blockquote contrast [#27](https://github.com/McShelby/hugo-theme-relearn/issues/27)
- [**feature**] expand: add option to open on page load [#25](https://github.com/McShelby/hugo-theme-relearn/issues/25)
- [**feature**] expand: rework styling [#24](https://github.com/McShelby/hugo-theme-relearn/issues/24)
- [**feature**] attachments: sort output [#23](https://github.com/McShelby/hugo-theme-relearn/issues/23)
- [**feature**] notice: make restyling of notice boxes more robust [#20](https://github.com/McShelby/hugo-theme-relearn/issues/20)
- [**feature**] notice: fix contrast issues [#19](https://github.com/McShelby/hugo-theme-relearn/issues/19)
- [**feature**] notice: align box colors to common standards [#18](https://github.com/McShelby/hugo-theme-relearn/issues/18)
- [**feature**] notice: use distinct icons for notice box type [#17](https://github.com/McShelby/hugo-theme-relearn/issues/17)
### Fixes
- [**bug**] attachments: support i18n for attachment size [#21](https://github.com/McShelby/hugo-theme-relearn/issues/21)
- [**bug**] notice: support i18n for box labels [#16](https://github.com/McShelby/hugo-theme-relearn/issues/16)
- [**bug**] notice: support multiple blocks in one box [#15](https://github.com/McShelby/hugo-theme-relearn/issues/15)
### Maintenance
- [**task**] dependency: upgrade jquery to 3.6.0 [#30](https://github.com/McShelby/hugo-theme-relearn/issues/30)
+++
## 1.1.1 (2021-07-04)
### Maintenance
- [**task**] theme: prepare for new hugo theme registration [#13](https://github.com/McShelby/hugo-theme-relearn/issues/13)
+++
## 1.1.0 (2021-07-02)
### Enhancements
- [**feature**] mermaid: expose options in config.toml [#4](https://github.com/McShelby/hugo-theme-relearn/issues/4)
### Fixes
- [**bug**] mermaid: config option for CDN url not used [#12](https://github.com/McShelby/hugo-theme-relearn/issues/12)
- [**bug**] mermaid: only highlight text in HTML elements [#10](https://github.com/McShelby/hugo-theme-relearn/issues/10)
- [**bug**] mermaid: support pan & zoom for graphs [#9](https://github.com/McShelby/hugo-theme-relearn/issues/9)
- [**bug**] mermaid: code fences not always rendered [#6](https://github.com/McShelby/hugo-theme-relearn/issues/6)
- [**bug**] mermaid: search term on load may bomb chart [#5](https://github.com/McShelby/hugo-theme-relearn/issues/5)
### Maintenance
- [**task**] mermaid: update to 8.10.2 [#7](https://github.com/McShelby/hugo-theme-relearn/issues/7)
+++
## 1.0.1 (2021-07-01)
### Maintenance
- [**task**] Prepare for hugo showcase [#3](https://github.com/McShelby/hugo-theme-relearn/issues/3)
+++
## 1.0.0 (2021-07-01)
### Maintenance
- [**task**] Fork project [#1](https://github.com/McShelby/hugo-theme-relearn/issues/1)

View File

@ -0,0 +1,11 @@
+++
chapter = true
title = "Basics"
weight = 1
+++
### Chapter 1
# Basics
Discover what this Hugo theme is all about and the core-concepts behind it.

View File

@ -0,0 +1,6 @@
+++
chapter = true
title = "Basics"
weight = 1
+++
{{< piratify >}}

View File

@ -0,0 +1,135 @@
+++
title = "Configuration"
weight = 20
+++
## Global site parameters
On top of [Hugo global configuration](https://gohugo.io/overview/configuration/), the Relearn theme lets you define the following parameters in your `config.toml` (here, values are default).
Note that some of these parameters are explained in details in other sections of this documentation.
```toml
[params]
# This controls whether submenus will be expanded (true), or collapsed (false) in the
# menu; if no setting is given, the first menu level is set to false, all others to true;
# this can be overridden in the pages frontmatter
alwaysopen = true
# Prefix URL to edit current page. Will display an "Edit this page" button on top right hand corner of every page.
# Useful to give opportunity to people to create merge request for your doc.
# See the config.toml file from this documentation site to have an example.
editURL = ""
# Author of the site, will be used in meta information
author = ""
# Description of the site, will be used in meta information
description = ""
# Shows a checkmark for visited pages on the menu
showVisitedLinks = false
# Disable search function. It will hide search bar
disableSearch = false
# Disable search in hidden pages, otherwise they will be shown in search box
disableSearchHiddenPages = false
# Disables hidden pages from showing up in the sitemap and on Google (et all), otherwise they may be indexed by search engines
disableSeoHiddenPages = false
# Disables hidden pages from showing up on the tags page although the tag term will be displayed even if all pages are hidden
disableTagHiddenPages = false
# Javascript and CSS cache are automatically busted when new version of site is generated.
# Set this to true to disable this behavior (some proxies don't handle well this optimization)
disableAssetsBusting = false
# Set this to true to disable copy-to-clipboard button for inline code.
disableInlineCopyToClipBoard = false
# A title for shortcuts in menu is set by default. Set this to true to disable it.
disableShortcutsTitle = false
# If set to false, a Home button will appear below the search bar on the menu.
# It is redirecting to the landing page of the current language if specified. (Default is "/")
disableLandingPageButton = true
# When using mulitlingual website, disable the switch language button.
disableLanguageSwitchingButton = false
# Hide breadcrumbs in the header and only show the current page title
disableBreadcrumb = true
# If set to true, prevents Hugo from including the Mermaid module if not needed (will reduce load times and traffic)
disableMermaid = false
# Specifies the remote location of the Mermaid js
customMermaidURL = "https://unpkg.com/mermaid@8.8.0/dist/mermaid.min.js"
# Initialization parameter for Mermaid, see Mermaid documentation
mermaidInitialize = "{ \"theme\": \"default\" }"
# Hide Next and Previous page buttons normally displayed full height beside content
disableNextPrev = true
# Order sections in menu by "weight" or "title". Default to "weight";
# this can be overridden in the pages frontmatter
ordersectionsby = "weight"
# Change default color scheme with a variant one. Can be "red", "blue", "green".
themeVariant = ""
# Provide a list of custom css files to load relative from the `static/` folder in the site root.
custom_css = ["css/foo.css", "css/bar.css"]
# Change the title separator. Default to "::".
titleSeparator = "-"
```
## A word on running your site in a subfolder
The theme runs best if your site is installed in the root of your webserver. If your site is served from a subfolder, eg. `https://example.com/mysite/`, you have to set the following lines to your `config.toml`
````toml
baseURL = "https://example.com/mysite/"
canonifyURLs = true
````
Without `canonifyURLs=true` URLs in sublemental pages (like `sitemap.xml`, `rss.xml`) will be generated falsly while your HTML files will still work. See https://github.com/gohugoio/hugo/issues/5226.
## Activate search
If not already present, add the follow lines in the same `config.toml` file.
```toml
[outputs]
home = [ "HTML", "RSS", "JSON"]
```
Relearn theme uses the last improvement available in hugo version 20+ to generate a json index file ready to be consumed by lunr.js javascript search engine.
> Hugo generate lunrjs index.json at the root of public folder.
> When you build the site with `hugo server`, hugo generates it internally and of course it doesnt show up in the filesystem
## Mermaid
The Mermaid configuration parameters can also be set on a specific page. In this case, the global parameter would be overwritten by the local one. See [Mermaid]({{< relref "shortcodes/mermaid.md" >}}) for additional documentation.
> Example:
>
> Mermaid is globally disabled. By default it won't be loaded by any page.
> On page "Architecture" you need a class diagram. You can set the Mermaid parameters locally to only load mermaid on this page (not on the others).
You also can disable Mermaid for specific pages while globally enabled.
## Home Button Configuration
If the `disableLandingPageButton` option is set to `false`, a Home button will appear
on the left menu. It is an alternative for clicking on the logo. To edit the
appearance, you will have to configure two parameters for the defined languages:
```toml
[Lanugages]
[Lanugages.en]
...
landingPageURL = "/"
landingPageName = "<i class='fas fa-home'></i> Home"
...
[Lanugages.pir]
...
landingPageURL = "/pir/"
landingPageName = "<i class='fas fa-home'></i> Arrr! Homme"
...
```
If those params are not configured for a specific language, they will get their
default values:
```toml
landingPageURL = "/"
landingPageName = "<i class='fas fa-home'></i> Home"
```
The home button is going to look like this:
![Default Home Button](/basics/configuration/images/home_button_defaults.png?width=100%)

View File

@ -0,0 +1,5 @@
+++
title = "Configurrrat'n"
weight = 20
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

View File

@ -0,0 +1,133 @@
+++
title = "Customization"
weight = 25
+++
The Relearn theme has been built to be as configurable as possible by defining multiple [partials](https://gohugo.io/templates/partials/)
In `themes/hugo-theme-relearn/layouts/partials/`, you will find all the partials defined for this theme. If you need to overwrite something, don't change the code directly. Instead [follow this page](https://gohugo.io/themes/customizing/). You'd create a new partial in the `layouts/partials` folder of your local project. This partial will have the priority.
This theme defines the following partials :
- *content*: the content page itself. This can be overridden if you wan't to display page's meta data above or below the content.
- *header*: the header of the content page (contains the breadcrumbs). _Not meant to be overwritten_
- *custom-header*: custom headers in page. Meant to be overwritten when adding CSS imports. Don't forget to include `style` HTML tag directive in your file
- *footer*: the footer of the content page (contains the arrows). _Not meant to be overwritten_
- *custom-footer*: custom footer in page. Meant to be overwritten when adding Javacript. Don't forget to include `javascript` HTML tag directive in your file
- *favicon*: the favicon
- *logo*: the logo, on top left hand corner.
- *meta*: HTML meta tags, if you want to change default behavior
- *menu*: left menu. _Not meant to be overwritten_
- *menu-pre*: side-wide configuration to prepend to menu items. If you override this, it is your responsiblity to take the page's `pre` setting into account.
- *menu-post*: side-wide configuration to append to menu items. If you override this, it is your responsiblity to take the page's `post` setting into account.
- *menu-footer*: footer of the the left menu
- *search*: search box
- *toc*: table of contents
## Change the logo
Create a new file in `layouts/partials/` named `logo.html`. Then write any HTML you want.
You could use an `img` HTML tag and reference an image created under the *static* folder, or you could paste a SVG definition!
{{% notice note %}}
The size of the logo will adapt automatically
{{% /notice %}}
## Change the favicon
If your favicon is a png, just drop off your image in your local `static/images/` folder and name it `favicon.png`
If you need to change this default behavior, create a new file in `layouts/partials/` named `favicon.html`. Then write something like this:
```html
<link rel="shortcut icon" href="/images/favicon.png" type="image/x-icon" />
```
## Change default colors {#theme-variant}
The Relearn theme let you choose between some predefined color scheme variants, but feel free to add one yourself!
### Standard variant
```toml
[params]
# Change default color scheme with a variant one. Can be empty, "red", "blue", "green".
themeVariant = ""
```
![Red variant](/basics/customization/images/standard-variant.png?width=60pc)
### Red variant
```toml
[params]
# Change default color scheme with a variant one. Can be empty, "red", "blue", "green".
themeVariant = "red"
```
![Red variant](/basics/customization/images/red-variant.png?width=60pc)
### Blue variant
```toml
[params]
# Change default color scheme with a variant one. Can be empty, "red", "blue", "green".
themeVariant = "blue"
```
![Blue variant](/basics/customization/images/blue-variant.png?width=60pc)
### Green variant
```toml
[params]
# Change default color scheme with a variant one. Can be empty, "red", "blue", "green".
themeVariant = "green"
```
![Green variant](/basics/customization/images/green-variant.png?width=60pc)
### 'Mine variant
First, create a new CSS file in your local `static/css` folder prefixed by `theme` (e.g. with _mine_ theme `static/css/theme-mine.css`). Copy the following content and modify colors in CSS variables.
```css
:root {
--MAIN-TEXT-color: #323232; /* Color of text by default */
--MAIN-TITLES-TEXT-color: #5e5e5e; /* Color of titles h2-h3-h4-h5-h6 */
--MAIN-LINK-color: #1C90F3; /* Color of links */
--MAIN-LINK-HOVER-color: #167ad0; /* Color of hovered links */
--MAIN-ANCHOR-color: #1C90F3; /* color of anchors on titles */
--MAIN-CODE-color: #e2e4e5; /* fallback color for code background */
--MAIN-CODE-BG-color: #282a36; /* fallback color for code text */
--MENU-HOME-LINK-color: #323232; /* Color of the home button text */
--MENU-HOME-LINK-HOVER-color: #5e5e5e; /* Color of the hovered home button text */
--MENU-HEADER-BG-color: #1C90F3; /* Background color of menu header */
--MENU-HEADER-BORDER-color: #33a1ff; /*Color of menu header border */
--MENU-SEARCH-BG-color: #167ad0; /* Search field background color (by default borders + icons) */
--MENU-SEARCH-BOX-color: #33a1ff; /* Override search field border color */
--MENU-SEARCH-BOX-ICONS-color: #a1d2fd; /* Override search field icons color */
--MENU-SECTIONS-ACTIVE-BG-color: #20272b; /* Background color of the active section and its children */
--MENU-SECTIONS-BG-color: #252c31; /* Background color of other sections */
--MENU-SECTIONS-LINK-color: #ccc; /* Color of links in menu */
--MENU-SECTIONS-LINK-HOVER-color: #e6e6e6; /* Color of links in menu, when hovered */
--MENU-SECTION-ACTIVE-CATEGORY-color: #777; /* Color of active category text */
--MENU-SECTION-ACTIVE-CATEGORY-BG-color: #fff; /* Color of background for the active category (only) */
--MENU-VISITED-color: #33a1ff; /* Color of 'page visited' icons in menu */
--MENU-SECTION-HR-color: #20272b; /* Color of <hr> separator in menu */
}
```
Then, set the `themeVariant` value with the name of your custom theme file. That's it!
```toml
[params]
# Change default color scheme with a variant one. Can be "red", "blue", "green".
themeVariant = "mine"
```

View File

@ -0,0 +1,5 @@
+++
title = "Customizat'n"
weight = 25
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 232 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 233 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 232 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 233 KiB

View File

@ -0,0 +1,5 @@
+++
title = "History"
weight = 30
+++
{{% include "basics/CHANGELOG.md" false %}}

View File

@ -0,0 +1,5 @@
+++
title = "Historrry"
weight = 30
+++
{{< piratify >}}

View File

@ -0,0 +1,102 @@
+++
title = "Installation"
weight = 15
+++
The following steps are here to help you initialize your new website. If you don't know Hugo at all, we strongly suggest you learn more about it by following this [great documentation for beginners](https://gohugo.io/overview/quickstart/).
## Create your project
Hugo provides a `new` command to create a new website.
```
hugo new site <new_project>
```
## Install the theme
Install the Relearn theme by following [this documentation](https://gohugo.io/getting-started/quick-start/#step-3-add-a-theme)
This theme's repository is: https://github.com/McShelby/hugo-theme-relearn.git
Alternatively, you can [download the theme as .zip](https://github.com/McShelby/hugo-theme-relearn/archive/main.zip) file and extract it in the `themes` directory
## Basic configuration
When building the website, you can set a theme by using `--theme` option. However, we suggest you modify the configuration file (`config.toml`) and set the theme as the default. You can also add the `[outputs]` section to enable the search functionality.
```toml
# Change the default theme to be use when building the site with Hugo
theme = "hugo-theme-relearn"
# For search functionality
[outputs]
home = [ "HTML", "RSS", "JSON"]
```
## Create your first chapter page
Chapters are pages that contain other child pages. It has a special layout style and usually just contains a _chapter name_, the _title_ and a _brief abstract_ of the section.
```markdown
### Chapter 1
# Basics
Discover what this Hugo theme is all about and the core concepts behind it.
```
renders as
![A Chapter](/basics/installation/images/chapter.png?classes=shadow&width=60pc)
The Relearn theme provides archetypes to create skeletons for your website. Begin by creating your first chapter page with the following command
```shell
hugo new --kind chapter basics/_index.md
```
By opening the given file, you should see the property `chapter=true` on top, meaning this page is a _chapter_.
By default all chapters and pages are created as a draft. If you want to render these pages, remove the property `draft: true` from the metadata.
## Create your first content pages
Then, create content pages inside the previously created chapter. Here are two ways to create content in the chapter:
```shell
hugo new basics/first-content.md
hugo new basics/second-content/_index.md
```
Feel free to edit those files by adding some sample content and replacing the `title` value in the beginning of the files.
## Launching the website locally
Launch by using the following command:
```shell
hugo serve
```
Go to `http://localhost:1313`
You should notice three things:
1. You have a left-side **Basics** menu, containing two submenus with names equal to the `title` properties in the previously created files.
2. The home page explains how to customize it by following the instructions.
3. When you run `hugo serve`, when the contents of the files change, the page automatically refreshes with the changes. Neat!
## Build the website
When your site is ready to deploy, run the following command:
```shell
hugo
```
A `public` folder will be generated, containing all static content and assets for your website. It can now be deployed on any web server.
{{% notice note %}}
This website can be automatically published and hosted with [Netlify](https://www.netlify.com/) (Read more about [Automated HUGO deployments with Netlify](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/)). Alternatively, you can use [GitHub pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/)
{{% /notice %}}

View File

@ -0,0 +1,5 @@
+++
title = "Installat'n"
weight = 15
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

View File

@ -0,0 +1,92 @@
+++
title = "What's new"
weight = 2
+++
This document shows you what's new in the latest release. For a detailed list of changes, see the [history page]({{%relref "basics/history" %}}).
**Breaking**: A change that requires action by you after upgrading to assure the site is still functional.
**Change**: A change in default behavior. This may requires action by you / may or may not be revertable by configuration.
**New**: Marks new behavior you might find interesting or comes configurable.
+++
## 2.6.0
- **New**: Your site can now be served from a subfolder if you set `baseURL` and `canonifyURLs=true` in your `config.toml`. See the [documentation]({{% relref "basics/configuration/#a-word-on-running-your-site-in-a-subfolder" %}}) for a detailed example.
+++
## 2.5.0
- **Change**: Add new colors `--MAIN-CODE-color` and `--MAIN-CODE-BG-color` for syntax highlightning fallback in your stylesheet in case `guessSyntax=true` is set. Ideally they are set to the same values as the ones from your chosen chroma style.
+++
## 2.4.0
- **Change**: Creation of customized stylesheets was simplified down to only contain the CSS variables. Everything else can and should be deleted from your custom stylesheet to assure everything works fine. For the predefined stylesheet variants, this change is already included. The [documentation]({{%relref "basics/customization/#mine-variant" %}}) was adjusted accordingly.
- **New**: Hidden pages are displayed by default in their according tags page. You can now turn off this behavior by setting `disableTagHiddenPages=true` in your `config.toml`.
- **New**: You can define the expansion state of your menus for the whole site by setting the `alwaysopen` option in your `config.toml`. Please see further [documentation]({{%relref "cont/pages/#override-expand-state-rules-for-menu-entries" %}}) for possible values and default behavior.
- **New**: New frontmatter `ordersectionsby` option to change immediate children sorting in menu and `children` shortcode. Possible values are `title` or `weight`.
- **New**: Alternate content of a page is now advertised in the HTML meta tags. See [Hugo documentation](https://gohugo.io/templates/rss/#reference-your-rss-feed-in-head).
+++
## 2.2.0
- **New**: Hidden pages are displayed by default in the sitemap generated by Hugo and are therefore visible for search engine indexing. You can now turn off this behavior by setting `disableSeoHiddenPages=true` in your `config.toml`.
+++
## 2.1.0
- **Change**: In case the site's structure contains addional *.md files not part of the site (eg files that are meant to be included by site pages - see CHANGELOG.md in exampleSite), they will now be ignored by the search.
- **New**: Hidden pages are indexed for the site search by default. You can now turn off this behavior by setting `disableSearchHiddenPages=true` in your `config.toml`.
- **New**: If a search term is found in an `expand` shortcode, the expand will be opened.
- **New**: The menu will scroll the active item into view on load.
+++
## 2.0.0
- **Change**: Syntaxhighlightning was switched to [built in Hugo mechanism](https://gohugo.io/content-management/syntax-highlighting/). You may need to configure a new stylesheet or decide to roll you own as describedd on in the Hugo documentation
- **Change**: In the predefined stylesheets there was a typo and `--MENU-HOME-LINK-HOVERED-color` must be changed to `--MENU-HOME-LINK-HOVER-color`.
- **Change**: `--MENU-HOME-LINK-color` and `--MENU-HOME-LINK-HOVER-color` were missing in the documentation. You should add them to your custom stylesheets.
- **Change**: Arrow navigation and `children` shortcode were ignoring setting for `ordersectionsby`. This is now changed and may result in different sorting order of your sub pages.
- **Change**: If hidden pages are accessed directly by typing their URL, they will be exposed in the menu.
- **Change**: A page without a `title` will be treated as `hidden=true`.
- **New**: You can define the expansion state of your menus in the frontmatter. Please see further [documentation]({{%relref "cont/pages/#override-expand-state-rules-for-menu-entries" %}}) for possible values and default behavior.
- **New**: New partials for defining pre/post content for menu items and the content. See [documentation]({{% relref "basics/customization" %}}) for further reading.
- **New**: Shortcode [`children`]({{% relref "shortcodes/children" %}}) with new parameter `containerstyle`.
- **New**: New shortcode [`include`]({{% relref "shortcodes/include" %}}) to include arbitrary file content into a page.
+++
## 1.2.0
- **New**: Shortcode [`expand`]({{% relref "shortcodes/expand" %}}) with new parameter to open on page load.
+++
## 1.1.0
- **New**: [`Mermaid`]({{% relref "shortcodes/mermaid#configuration" %}}) config options can be set in `config.toml`.

View File

@ -0,0 +1,5 @@
+++
title = "Migrrrat'n"
weight = 17
+++
{{< piratify >}}

View File

@ -0,0 +1,11 @@
+++
disableToc = true
title = "Requirements"
weight = 10
+++
Thanks to the simplicity of Hugo, this page is as empty as this theme needs requirements.
Just download latest version of [Hugo binary (> 0.25)](https://gohugo.io/getting-started/installing/) for your OS (Windows, Linux, Mac) : it's that simple.
![Magic](/basics/requirements/images/magic.gif?classes=shadow)

View File

@ -0,0 +1,6 @@
+++
disableToc = true
title = "Requirrrements"
weight = 10
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.4 MiB

View File

@ -0,0 +1,11 @@
+++
chapter = true
title = "Content"
weight = 2
+++
### Chapter 2
# Content
Find out how to create and organize your content quickly and intuitively.

View File

@ -0,0 +1,6 @@
+++
chapter = true
title = "Rambl'n"
weight = 2
+++
{{< piratify >}}

View File

@ -0,0 +1,58 @@
+++
title = "Archetypes"
weight = 10
+++
Using the command: `hugo new [relative new content path]`, you can start a content file with the date and title automatically set. While this is a welcome feature, active writers need more: [archetypes](https://gohugo.io/content/archetypes/).
It is pre-configured skeleton pages with default front matter. Please refer to the documentation for types of page to understand the differences.
## Chapter {#archetypes-chapter}
To create a Chapter page, run the following commands
```shell
hugo new --kind chapter <name>/_index.md
```
It will create a page with predefined Front-Matter:
```toml
+++
chapter = true
pre = "<b>X. </b>"
title = "{{ replace .Name "-" " " | title }}"
weight = 5
+++
### Chapter X
# Some Chapter title
Lorem Ipsum.
```
## Default
To create a default page, run either one of the following commands either
```shell
hugo new <chapter>/<name>/_index.md
```
or
```shell
hugo new <chapter>/<name>.md
```
It will create a page with predefined Front-Matter:
```toml
+++
title = "{{ replace .Name "-" " " | title }}"
weight = 5
+++
Lorem Ipsum.
```

View File

@ -0,0 +1,5 @@
+++
title = "Arrrchetypes"
weight = 10
+++
{{< piratify >}}

View File

@ -0,0 +1,71 @@
+++
title = "Multilingual and i18n"
weight = 30
+++
The Relearn theme is fully compatible with Hugo multilingual mode.
It provides:
- Translation strings for default values (English, Arabic, Dutch, Piratized English, German, Hindi, Indonesian, Japanese, Piratized English, Portuguese, Russian, Simplified Chinese, Spanish, Turkish). Feel free to contribute!
- Automatic menu generation from multilingual content
- In-browser language switching
![I18n menu](/cont/i18n/images/i18n-menu.gif)
## Basic configuration
After learning [how Hugo handle multilingual websites](https://gohugo.io/content-management/multilingual), define your languages in your `config.toml` file.
For example with current English and Piratized English website.
```toml
# English is the default language
defaultContentLanguage = "en"
[Languages]
[Languages.en]
title = "Documentation for Hugo Relearn Theme"
weight = 1
languageName = "English"
[Languages.pir]
title = "Documentat'n fer Cap'n Hugo Relearrrn Theme"
weight = 2
languageName = "Arrr! Pirrrates"
```
Then, for each new page, append the *id* of the language to the file.
- Single file `my-page.md` is split in two files:
- in English: `my-page.md`
- in Piratized English: `my-page.pir.md`
- Single file `_index.md` is split in two files:
- in English: `_index.md`
- in Piratized English: `_index.pir.md`
{{% notice info %}}
Be aware that only translated pages are displayed in menu. It's not replaced with default language content.
{{% /notice %}}
{{% notice tip %}}
Use [slug](https://gohugo.io/content-management/multilingual/#translate-your-content) Front Matter parameter to translate urls too.
{{% /notice %}}
## Overwrite translation strings
Translations strings are used for common default values used in the theme (*Edit this page* button, *Search placeholder* and so on). Translations are available in English and Piratized English but you may use another language or want to override default values.
To override these values, create a new file in your local i18n folder `i18n/<idlanguage>.toml` and inspire yourself from the theme `themes/hugo-theme-relearn/i18n/en.toml`
## Disable language switching
Switching the language in the browser is a great feature, but for some reasons you may want to disable it.
Just set `disableLanguageSwitchingButton=true` in your `config.toml`
```toml
[params]
# When using mulitlingual website, disable the switch language button.
disableLanguageSwitchingButton = true
```

View File

@ -0,0 +1,5 @@
+++
title = "Multilingual an' i18n"
weight = 30
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

View File

@ -0,0 +1,41 @@
+++
title = "Icons and logos"
weight = 27
+++
The Relearn theme for Hugo loads the [**Font Awesome**](https://fontawesome.com) library, allowing you to easily display any icon or logo available in the Font Awesome free collection.
## Finding an icon
Browse through the available icons in the [Font Awesome Gallery](https://fontawesome.com/icons?d=gallery&m=free). Notice that the **free** filter is enabled, as only the free icons are available by default.
Once on the Font Awesome page for a specific icon, for example the page for the [heart](https://fontawesome.com/icons/heart?style=solid), copy the HTML reference and paste into the Markdown content.
The HTML to include the heart icon is:
```html
<i class="fas fa-heart"></i>
```
## Including in markdown
Paste the `<i>` HTML into markup and Font Awesome will load the relevant icon.
```html
Built with <i class="fas fa-heart"></i> by Relearn and Hugo
```
Which appears as
Built with <i class="fas fa-heart"></i> by Relearn and Hugo
## Customising icons
Font Awesome provides many ways to modify the icon
* Change colour (by default the icon will inherit the parent colour)
* Increase or decrease size
* Rotate
* Combine with other icons
Check the full documentation on [web fonts with CSS](https://fontawesome.com/how-to-use/web-fonts-with-css) for more.

View File

@ -0,0 +1,5 @@
+++
title = "Ay'cons an' logos"
weight = 27
+++
{{< piratify >}}

View File

@ -0,0 +1,696 @@
+++
title = "Markdown syntax"
weight = 15
+++
Let's face it: Writing content for the Web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.
**Markdown** is a better way to write **HTML**, without all the complexities and ugliness that usually accompanies it.
Some of the key benefits are:
1. Markdown is simple to learn, with minimal extra characters so it's also quicker to write content.
2. Less chance of errors when writing in Markdown.
3. Produces valid XHTML output.
4. Keeps the content and the visual display separate, so you cannot mess up the look of your site.
5. Write in any text editor or Markdown application you like.
6. Markdown is a joy to use!
John Gruber, the author of Markdown, puts it like this:
> The overriding design goal for Markdowns formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like its been marked up with tags or formatting instructions. While Markdowns syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdowns syntax is the format of plain text email.
> <cite>John Gruber</cite>
Without further delay, let us go over the main elements of Markdown and what the resulting HTML looks like:
{{% notice info %}}
<i class="fas fa-bookmark"></i> Bookmark this page and the [official Commonmark reference](https://commonmark.org/help/) for easy future reference!
{{% /notice %}}
## Headings
Headings from `h1` through `h6` are constructed with a `#` for each level:
```markdown
# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
```
Renders to:
<!-- markdownlint-disable MD025 -->
# h1 Heading
<!-- markdownlint-enable MD025 -->
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
HTML:
```html
<h1>h1 Heading</h1>
<h2>h2 Heading</h2>
<h3>h3 Heading</h3>
<h4>h4 Heading</h4>
<h5>h5 Heading</h5>
<h6>h6 Heading</h6>
```
## Comments
Comments should be HTML compatible
```html
<!--
This is a comment
-->
```
Comment below should **NOT** be seen:
<!--
This is a comment
-->
## Horizontal Rules
The HTML `<hr>` element is for creating a "thematic break" between paragraph-level elements. In Markdown, you can create a `<hr>` with `+++` - three consecutive dashes
renders to:
+++
## Paragraphs
Any text not starting with a special sign is written as normal, plain text and will be wrapped within `<p></p>` tags in the rendered HTML.
So this body copy:
```markdown
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
```
renders to this HTML:
```html
<p>Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.</p>
```
## Text Markers
### Bold
For emphasizing a snippet of text with a heavier font-weight.
The following snippet of text is **rendered as bold text**.
```markdown
**rendered as bold text**
```
renders to:
<!-- markdownlint-disable MD036 -->
**rendered as bold text**
<!-- markdownlint-enable MD036 -->
and this HTML
```html
<strong>rendered as bold text</strong>
```
### Italics
For emphasizing a snippet of text with italics.
The following snippet of text is _rendered as italicized text_.
```markdown
_rendered as italicized text_
```
renders to:
<!-- markdownlint-disable MD036 -->
_rendered as italicized text_
<!-- markdownlint-enable MD036 -->
and this HTML:
```html
<em>rendered as italicized text</em>
```
### Strikethrough
In GFM (GitHub flavored Markdown) you can do strikethroughs.
```markdown
~~Strike through this text.~~
```
Which renders to:
~~Strike through this text.~~
HTML:
```html
<del>Strike through this text.</del>
```
## Blockquotes
For quoting blocks of content from another source within your document.
Add `>` before any text you want to quote.
```markdown
> **Fusion Drive** combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.
```
Renders to:
> **Fusion Drive** combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.
and this HTML:
```html
<blockquote>
<p><strong>Fusion Drive</strong> combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.</p>
</blockquote>
```
Blockquotes can also be nested:
```markdown
> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
```
Renders to:
> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
## Lists
### Unordered
A list of items in which the order of the items does not explicitly matter.
You may use any of the following symbols to denote bullets for each list item:
```markdown
* valid bullet
- valid bullet
+ valid bullet
```
For example
```markdown
+ Lorem ipsum dolor sit amet
+ Consectetur adipiscing elit
+ Integer molestie lorem at massa
+ Facilisis in pretium nisl aliquet
+ Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
+ Faucibus porta lacus fringilla vel
+ Aenean sit amet erat nunc
+ Eget porttitor lorem
```
Renders to:
<!-- markdownlint-disable MD004 -->
+ Lorem ipsum dolor sit amet
+ Consectetur adipiscing elit
+ Integer molestie lorem at massa
+ Facilisis in pretium nisl aliquet
+ Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
+ Faucibus porta lacus fringilla vel
+ Aenean sit amet erat nunc
+ Eget porttitor lorem
<!-- markdownlint-enable MD004 -->
And this HTML
```html
<ul>
<li>Lorem ipsum dolor sit amet</li>
<li>Consectetur adipiscing elit</li>
<li>Integer molestie lorem at massa</li>
<li>Facilisis in pretium nisl aliquet</li>
<li>Nulla volutpat aliquam velit
<ul>
<li>Phasellus iaculis neque</li>
<li>Purus sodales ultricies</li>
<li>Vestibulum laoreet porttitor sem</li>
<li>Ac tristique libero volutpat at</li>
</ul>
</li>
<li>Faucibus porta lacus fringilla vel</li>
<li>Aenean sit amet erat nunc</li>
<li>Eget porttitor lorem</li>
</ul>
```
### Ordered
A list of items in which the order of items does explicitly matter.
```markdown
1. Lorem ipsum dolor sit amet
4. Consectetur adipiscing elit
2. Integer molestie lorem at massa
8. Facilisis in pretium nisl aliquet
4. Nulla volutpat aliquam velit
99. Faucibus porta lacus fringilla vel
21. Aenean sit amet erat nunc
6. Eget porttitor lorem
```
Renders to:
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa
4. Facilisis in pretium nisl aliquet
5. Nulla volutpat aliquam velit
6. Faucibus porta lacus fringilla vel
7. Aenean sit amet erat nunc
8. Eget porttitor lorem
And this HTML:
```html
<ol>
<li>Lorem ipsum dolor sit amet</li>
<li>Consectetur adipiscing elit</li>
<li>Integer molestie lorem at massa</li>
<li>Facilisis in pretium nisl aliquet</li>
<li>Nulla volutpat aliquam velit</li>
<li>Faucibus porta lacus fringilla vel</li>
<li>Aenean sit amet erat nunc</li>
<li>Eget porttitor lorem</li>
</ol>
```
{{% notice tip %}}
If you just use `1.` for each number, Markdown will automatically number each item. For example:
{{% /notice %}}
```markdown
1. Lorem ipsum dolor sit amet
1. Consectetur adipiscing elit
1. Integer molestie lorem at massa
1. Facilisis in pretium nisl aliquet
1. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
1. Eget porttitor lorem
```
Renders to:
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa
4. Facilisis in pretium nisl aliquet
5. Nulla volutpat aliquam velit
6. Faucibus porta lacus fringilla vel
7. Aenean sit amet erat nunc
8. Eget porttitor lorem
## Code
### Inline code
Wrap inline snippets of code with `` ` ``.
```markdown
In this example, `<div></div>` should be wrapped as **code**.
```
Renders to:
In this example, `<div></div>` should be wrapped as **code**.
HTML:
```html
<p>In this example, <code>&lt;div&gt;&lt;/div&gt;</code> should be wrapped as <strong>code</strong>.</p>
```
### Indented code
Or indent several lines of code by at least two spaces, as in:
```markdown
// Some comments
line 1 of code
line 2 of code
line 3 of code
```
Renders to:
<!-- markdownlint-disable MD046 -->
// Some comments
line 1 of code
line 2 of code
line 3 of code
<!-- markdownlint-enable MD046 -->
HTML:
```html
<pre>
<code>
// Some comments
line 1 of code
line 2 of code
line 3 of code
</code>
</pre>
```
### Block code "fences"
Use "fences" ```` ``` ```` to block in multiple lines of code.
````plaintext
```
Sample text here...
```
````
HTML:
```html
<pre>
<code>Sample text here...</code>
</pre>
```
### Syntax highlighting
GFM, or "GitHub Flavored Markdown" also supports syntax highlighting. To activate it, usually you simply add the file extension of the language you want to use directly after the first code "fence", ` ```js `, and syntax highlighting will automatically be applied in the rendered HTML.
See [Code Highlighting]({{% relref "syntaxhighlight" %}}) for additional documentation.
For example, to apply syntax highlighting to JavaScript code:
````plaintext
```js
grunt.initConfig({
assemble: {
options: {
assets: 'docs/assets',
data: 'src/data/*.{json,yml}',
helpers: 'src/custom-helpers.js',
partials: ['src/partials/**/*.{hbs,md}']
},
pages: {
options: {
layout: 'default.hbs'
},
files: {
'./': ['src/templates/pages/index.hbs']
}
}
}
};
```
````
Renders to:
```js
grunt.initConfig({
assemble: {
options: {
assets: 'docs/assets',
data: 'src/data/*.{json,yml}',
helpers: 'src/custom-helpers.js',
partials: ['src/partials/**/*.{hbs,md}']
},
pages: {
options: {
layout: 'default.hbs'
},
files: {
'./': ['src/templates/pages/index.hbs']
}
}
}
};
```
## Tables
Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.
```markdown
| Option | Description |
| ++++++ | +++++++++-- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
```
Renders to:
| Option | Description |
| ++++++ | +++++++++-- |
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
And this HTML:
```html
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td>data</td>
<td>path to data files to supply the data that will be passed into templates.</td>
</tr>
<tr>
<td>engine</td>
<td>engine to be used for processing templates. Handlebars is the default.</td>
</tr>
<tr>
<td>ext</td>
<td>extension to be used for dest files.</td>
</tr>
</table>
```
### Right aligned text
Adding a colon on the right side of the dashes below any heading will right align text for that column.
```markdown
| Option | Description |
| ++++++:| +++++++++--:|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
```
| Option | Description |
| ++++++:| +++++++++--:|
| data | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext | extension to be used for dest files. |
### Two tables adjacent
| Option | Description |
| ++++++ | +++++++++-- |
| ext | extension to be used for dest files. |
| Option | Description |
| ++++++ | +++++++++-- |
| ext | extension to be used for dest files. |
## Links
### Basic link
```markdown
[Assemble](http://assemble.io)
```
Renders to (hover over the link, there is no tooltip):
[Assemble](http://assemble.io)
HTML:
```html
<a href="http://assemble.io">Assemble</a>
```
### Add a tooltip
```markdown
[Upstage](https://github.com/upstage/ "Visit Upstage!")
```
Renders to (hover over the link, there should be a tooltip):
[Upstage](https://github.com/upstage/ "Visit Upstage!")
HTML:
```html
<a href="https://github.com/upstage/" title="Visit Upstage!">Upstage</a>
```
### Named Anchors
Named anchors enable you to jump to the specified anchor point on the same page. For example, each of these chapters:
```markdown
# Table of Contents
* [Chapter 1](#chapter-1)
* [Chapter 2](#chapter-2)
* [Chapter 3](#chapter-3)
```
will jump to these sections:
```markdown
## Chapter 1 <a id="chapter-1"></a>
Content for chapter one.
## Chapter 2 <a id="chapter-2"></a>
Content for chapter one.
## Chapter 3 <a id="chapter-3"></a>
Content for chapter one.
```
**NOTE** that specific placement of the anchor tag seems to be arbitrary. They are placed inline here since it seems to be unobtrusive, and it works.
## Images {#images}
Images have a similar syntax to links but include a preceding exclamation point.
```markdown
![Minion](https://octodex.github.com/images/minion.png)
```
![Minion](https://octodex.github.com/images/minion.png)
or
```markdown
![Alt text](https://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")
```
![Alt text](https://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")
Like links, Images also have a footnote style syntax
### Alternative usage : note images
```markdown
![Alt text][id]
```
![Alt text][id]
With a reference later in the document defining the URL location:
[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat"
[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat"
### Further image formatting
The Hugo Markdown parser supports additional non-standard functionality.
#### Resizing image
Add HTTP parameters `width` and/or `height` to the link image to resize the image. Values are CSS values (default is `auto`).
```markdown
![Minion](https://octodex.github.com/images/minion.png?width=20pc)
```
![Minion](https://octodex.github.com/images/minion.png?width=20pc)
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.png?width=20pc)
```markdown
![Minion](https://octodex.github.com/images/minion.png?height=50px)
```
![Minion](https://octodex.github.com/images/minion.png?height=50px)
```markdown
![Minion](https://octodex.github.com/images/minion.png?height=50px&width=300px)
```
![Minion](https://octodex.github.com/images/minion.png?height=50px&width=300px)
#### Add CSS classes
Add a HTTP `classes` parameter to the link image to add CSS classes. `shadow`and `border` are available but you could define other ones.
```markdown
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg?classes=shadow)
```
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg?width=40pc&classes=shadow)
```markdown
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg?classes=border)
```
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg?width=40pc&classes=border)
```markdown
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg?classes=border,shadow)
```
![stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg?width=40pc&classes=border,shadow)
#### Lightbox
Add a HTTP `featherlight` parameter to the link image to disable lightbox. By default lightbox is enabled using the featherlight.js plugin. You can disable this by defining `featherlight` to `false`.
```markdown
![Minion](https://octodex.github.com/images/minion.png?featherlight=false)
```
![Minion](https://octodex.github.com/images/minion.png?featherlight=false)

View File

@ -0,0 +1,5 @@
+++
title = "Marrrkdown rules"
weight = 15
+++
{{< piratify >}}

View File

@ -0,0 +1,113 @@
+++
title = "Menu extra shortcuts"
weight = 25
+++
You can define additional menu entries or shortcuts in the navigation menu without any link to content.
## Basic configuration
Edit the website configuration `config.toml` and add a `[[menu.shortcuts]]` entry for each link your want to add.
Example from the current website:
````toml
[[menu.shortcuts]]
name = "<i class='fab fa-github'></i> GitHub repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
weight = 10
[[menu.shortcuts]]
name = "<i class='fas fa-camera'></i> Showcases"
url = "/showcase"
weight = 11
[[menu.shortcuts]]
name = "<i class='fas fa-bookmark'></i> Hugo Documentation"
identifier = "hugodoc"
url = "https://gohugo.io/"
weight = 20
[[menu.shortcuts]]
name = "<i class='fas fa-bullhorn'></i> Credits"
url = "/credits"
weight = 30
````
By default, shortcuts are preceded by a title. This title can be disabled by setting `disableShortcutsTitle=true`.
However, if you want to keep the title but change its value, it can be overriden by changing your local i18n translation string configuration.
For example, in your local `i18n/en.toml` file, add the following content
````toml
[Shortcuts-Title]
other = "<Your value>"
````
Read more about [hugo menu](https://gohugo.io/extras/menus/) and [hugo i18n translation strings](https://gohugo.io/content-management/multilingual/#translation-of-strings)
## Configuration for Multilingual mode {#i18n}
When using a multilingual website, you can set different menus for each language. In the `config.toml` file, prefix your menu configuration by `Languages.<language-id>`.
Example from the current website:
````toml
[Languages]
[Languages.en]
title = "Documentation for Hugo Relearn Theme"
weight = 1
languageName = "English"
[[Languages.en.menu.shortcuts]]
name = "<i class='fab fa-github'></i> GitHub repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
weight = 10
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-camera'></i> Showcases"
url = "/showcase"
weight = 11
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-bookmark'></i> Hugo Documentation"
identifier = "hugodoc"
url = "https://gohugo.io/"
weight = 20
[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-bullhorn'></i> Credits"
url = "/credits"
weight = 30
[Languages.pir]
title = "Documentat'n fer Cap'n Hugo Relearrrn Theme"
weight = 2
languageName = "Arrr! Pirrrates"
[[Languages.pir.menu.shortcuts]]
name = "<i class='fab fa-github'></i> GitHub repo"
identifier = "ds"
url = "https://github.com/McShelby/hugo-theme-relearn"
weight = 10
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-camera'></i> Showcases"
url = "/showcase"
weight = 11
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-bookmark'></i> Cap'n Hugo Documentat'n"
identifier = "hugodoc"
url = "https://gohugo.io/"
weight = 20
[[Languages.pir.menu.shortcuts]]
name = "<i class='fas fa-bullhorn'></i> Crrredits"
url = "/credits"
weight = 30
````
Read more about [hugo menu](https://gohugo.io/extras/menus/) and [hugo multilingual menus](https://gohugo.io/content-management/multilingual/#menus)

View File

@ -0,0 +1,5 @@
+++
title = "Menu extrrra shorrrtcuts"
weight = 25
+++
{{< piratify >}}

View File

@ -0,0 +1,186 @@
+++
title = "Pages organization"
weight = 5
+++
In **Hugo**, pages are the core of your site. Once it is configured, pages are definitely the added value to your documentation site.
## Folders
Organize your site like [any other Hugo project](https://gohugo.io/content/organization/). Typically, you will have a *content* folder with all your pages.
````plaintext
content
├── level-one
│ ├── level-two
│ │ ├── level-three
│ │ │ ├── level-four
│ │ │ │ ├── _index.md <-- /level-one/level-two/level-three/level-four
│ │ │ │ ├── page-4-a.md <-- /level-one/level-two/level-three/level-four/page-4-a
│ │ │ │ ├── page-4-b.md <-- /level-one/level-two/level-three/level-four/page-4-b
│ │ │ │ └── page-4-c.md <-- /level-one/level-two/level-three/level-four/page-4-c
│ │ │ ├── _index.md <-- /level-one/level-two/level-three
│ │ │ ├── page-3-a.md <-- /level-one/level-two/level-three/page-3-a
│ │ │ ├── page-3-b.md <-- /level-one/level-two/level-three/page-3-b
│ │ │ └── page-3-c.md <-- /level-one/level-two/level-three/page-3-c
│ │ ├── _index.md <-- /level-one/level-two
│ │ ├── page-2-a.md <-- /level-one/level-two/page-2-a
│ │ ├── page-2-b.md <-- /level-one/level-two/page-2-b
│ │ └── page-2-c.md <-- /level-one/level-two/page-2-c
│ ├── _index.md <-- /level-one
│ ├── page-1-a.md <-- /level-one/page-1-a
│ ├── page-1-b.md <-- /level-one/page-1-b
│ └── page-1-c.md <-- /level-one/page-1-c
├── _index.md <-- /
└── page-top.md <-- /page-top
````
{{% notice note %}}
`_index.md` is required in each folder, its your “folder home page”
{{% /notice %}}
## Types
The Relearn theme defines two types of pages. *Default* and *Chapter*. Both can be used at any level of the documentation, the only difference being layout display.
A **Chapter** displays a page meant to be used as introduction for a set of child pages. Commonly, it contains a simple title and a catch line to define content that can be found under it.
You can define any HTML as prefix for the menu. In the example below, it's just a number but that could be an [icon](https://fortawesome.github.io/Font-Awesome/).
![Chapter page](/cont/pages/images/pages-chapter.png?width=50pc)
```markdown
+++
chapter = true
pre = "<b>1. </b>"
title = "Basics"
weight = 5
+++
### Chapter 1
# Basics
Discover what this Hugo theme is all about and the core-concepts behind it.
```
To tell the Relearn theme to consider a page as a chapter, set `chapter=true` in the Front Matter of the page.
A **Default** page is any other content page.
![Default page](/cont/pages/images/pages-default.png?width=50pc)
```toml
+++
title = "Installation"
weight = 15
+++
```
The following steps are here to help you initialize your new website. If you don't know Hugo at all, we strongly suggest you to train by following this [great documentation for beginners](https://gohugo.io/overview/quickstart/).
## Create your project
Hugo provides a `new` command to create a new website.
```shell
hugo new site <new_project>
```
The Relearn theme provides [archetypes]({{%relref "cont/archetypes" %}}) to help you create this kind of pages.
## Front Matter configuration
Each Hugo page has to define a [Front Matter](https://gohugo.io/content/front-matter/) in *toml*, *yaml* or *json*. This site will use *toml* in all cases.
The Relearn theme uses the following parameters on top of Hugo ones :
```toml
+++
# Table of contents (toc) is enabled by default. Set this parameter to true to disable it.
# Note: Toc is always disabled for chapter pages
disableToc = "false"
# If set, this will be used for the page's menu entry (instead of the `title` attribute)
menuTitle = ""
# If set, this will explicitly override common rules for the expand state of a page's menu entry
alwaysopen = true
# If set, this will explicitly override common rules for the sorting order of a page's submenu entries
ordersectionsby = "title"
# The title of the page in menu will be prefixed by this HTML content
pre = ""
# The title of the page in menu will be postfixed by this HTML content
post = ""
# Set the page as a chapter, changing the way it's displayed
chapter = false
# Hide a menu entry by setting this to true
hidden = false
# Display name of this page modifier. If set, it will be displayed in the footer.
LastModifierDisplayName = ""
# Email of this page modifier. If set with LastModifierDisplayName, it will be displayed in the footer
LastModifierEmail = ""
+++
```
### Add icon to a menu entry
In the page frontmatter, add a `pre` param to insert any HTML code before the menu label. The example below uses the GitHub icon.
```toml
+++
title = "GitHub repo"
pre = "<i class='fab fa-github'></i> "
+++
```
![Title with icon](/cont/pages/images/frontmatter-icon.png)
### Ordering sibling menu/page entries
Hugo provides a [flexible way](https://gohugo.io/content/ordering/) to handle order for your pages.
The simplest way is to set `weight` parameter to a number.
```toml
+++
title = "My page"
weight = 5
+++
```
### Using a custom title for menu entries
By default, the Relearn theme will use a page's `title` attribute for the menu item (or `linkTitle` if defined).
But a page's title has to be descriptive on its own while the menu is a hierarchy.
We've added the `menuTitle` parameter for that purpose:
For example (for a page named `content/install/linux.md`):
```toml
+++
title = "Install on Linux"
menuTitle = "Linux"
+++
```
### Override expand state rules for menu entries
You can change how the theme expands menu entries on the side of the content with the `alwaysopen` setting on a per page basis. If `alwaysopen=false` for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.
The theme generates the menu based on the following rules:
- all parent entries of the active page including their siblings are shown regardless of any settings
- immediate children entries of the active page are shown regardless of any settings
- if not overridden, all other first level entries behave like they would have been given `alwaysopen=false`
- if not overridden, all other entries of levels besides the first behave like they would have been given `alwaysopen=true`
- all visible entries show their immediate children entries if `alwaysopen=true`; this proceeds recursivley
- all remaining entries are not shown
You can see this feature in action on the example page for [children shortcode]({{< relref "shortcodes/children" >}}) and its children pages.
## Your Page
To configure your page, you basically have three choices:
1. Create an `_index.md` document in `content` folder and fill the file with *Markdown content*
2. Create an `index.html` file in the `static` folder and fill the file with *HTML content*
3. Configure your server to automatically redirect home page to one your documentation page

View File

@ -0,0 +1,5 @@
+++
title = "Planks orrrganizat'n"
weight = 5
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 107 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 188 KiB

View File

@ -0,0 +1,61 @@
+++
title = "Code highlighting"
weight = 16
+++
The Relearn theme uses [Hugo's built-in syntax highlighting](https://gohugo.io/content-management/syntax-highlighting/) for code.
## Markdown syntax
Wrap the code block with three backticks and the name of the language. Highlight will try to auto detect the language if one is not provided.
<!-- markdownlint-disable MD046 -->
````plaintext
```json
[
{
"title": "apples",
"count": [12000, 20000],
"description": {"text": "...", "sensitive": false}
},
{
"title": "oranges",
"count": [17500, null],
"description": {"text": "...", "sensitive": false}
}
]
```
````
<!-- markdownlint-disable MD046 -->
Renders to:
```json
[
{
"title": "apples",
"count": [12000, 20000],
"description": {"text": "...", "sensitive": false}
},
{
"title": "oranges",
"count": [17500, null],
"description": {"text": "...", "sensitive": false}
}
]
```
## Supported languages
Hugo comes with a [remarkable list](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) of supported languages.
## Recommended configuration
You can choose a color theme from the [list of supported themes](https://xyproto.github.io/splash/docs/all.html) and add it in your `config.toml`
````toml
[markup]
[markup.highlight]
style = "base16-snazzy" # choose a color theme or create your own
guessSyntax = false # if set to true, avoid unstyled code if no language was given but mermaid code fences will not work anymore
````

View File

@ -0,0 +1,5 @@
+++
title = "Code highlight'n"
weight = 16
+++
{{< piratify >}}

View File

@ -0,0 +1,36 @@
+++
tags = ["documentation", "tutorial"]
title = "Tags"
weight = 40
+++
The Relearn theme supports one default taxonomy of Hugo: the *tag* feature.
## Configuration
Just add tags to any page:
```toml
+++
tags = ["tutorial", "theme"]
title = "Theme tutorial"
weight = 15
+++
```
## Behavior
The tags are displayed at the top of the page, in their insertion order.
Each tag is a link to a *Taxonomy* page displaying all the articles with the given tag.
## List all the tags
In the `config.toml` file you can add a shortcut to display all the tags
```toml
[[menu.shortcuts]]
name = "<i class='fas fa-tags'></i> Tags"
url = "/tags"
weight = 30
```

View File

@ -0,0 +1,6 @@
+++
tags = ["documentat'n", "tutorrrial"]
title = "Tags"
weight = 40
+++
{{< piratify >}}

View File

@ -0,0 +1,27 @@
+++
disableToc = true
title = "Credits"
+++
## Contributors
Special thanks to [everyone who has contributed](https://github.com/McShelby/hugo-theme-relearn/graphs/contributors) to this project.
Many thanks to [@matcornic](https://github.com/matcornic) for his work on the [Learn theme](https://github.com/matcornic/hugo-theme-learn).
## Packages and libraries
* [Mermaid](https://mermaid-js.github.io/mermaid) - generation of diagram and flowchart from text in a similar manner as Markdown
* [font awesome](http://fontawesome.io/) - the iconic font and CSS framework
* [jQuery](https://jquery.com) - The Write Less, Do More, JavaScript Library
* [jquery-svg-zoom-pan](https://github.com/DanielHoffmann/jquery-svg-pan-zoom) - enable pan and zoom in Mermaid graphs
* [lunr](https://lunrjs.com) - Lunr enables you to provide a great search experience without the need for external, server-side, search services...
* [clipboard.js](https://zenorocha.github.io/clipboard.js) - copy text to clipboard
* [modernizr](https://modernizr.com) - A JavaScript toolkit that allows web developers to use new CSS3 and HTML5 features while maintaining a fine level of control over browsers that don't support
## Tooling
* [gren](https://github.com/github-tools/github-release-notes) - Releasenotes generator
* [Hugo](https://gohugo.io/) - Static site generator
* [Netlify](https://www.netlify.com) - Continuous deployement and hosting of this documentation
* [Wercker](https://app.wercker.com) - Continous testing

View File

@ -0,0 +1,5 @@
+++
disableToc = true
title = "Crrredits"
+++
{{< piratify >}}

View File

@ -0,0 +1,14 @@
You can add:
- multiple paragraphs
- bullet point lists
- _emphasized_, **bold** and even **_bold emphasized_** text
- [links](https://example.com)
- other shortcodes besides `include`
- etc.
```plaintext
...and even source code
```
> the possiblities are endless

View File

@ -0,0 +1,19 @@
+++
chapter = true
title = "Shortcodes"
weight = 3
+++
### Chapter 3
# Shortcodes
Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesnt support well. You could use pure HTML to expand possibilities.
But this happens to be a bad idea. Everyone uses Markdown because it's pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.
To avoid this limitations, Hugo created [shortcodes](https://gohugo.io/extras/shortcodes/). A shortcode is a simple snippet inside a page.
The Relearn theme provides multiple shortcodes on top of existing ones.
{{%children containerstyle="div" style="h2" description="true" %}}

View File

@ -0,0 +1,6 @@
+++
chapter = true
title = "Shorrrtcodes"
weight = 3
+++
{{< piratify >}}

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

View File

@ -0,0 +1 @@
This is a small text

View File

@ -0,0 +1,94 @@
+++
description = "The Attachments shortcode displays a list of files attached to a page"
title = "Attachments"
+++
The Attachments shortcode displays a list of files attached to a page.
{{% attachments /%}}
## Usage
The shortcurt lists files found in a **specific folder**.
Currently, it support two implementations for pages
1. If your page is a Markdown file, attachements must be placed in a **folder** named like your page and ending with **.files**.
> * content
> * _index.md
> * page.files
> * attachment.pdf
> * page.md
2. If your page is a **folder**, attachements must be placed in a nested **'files'** folder.
> * content
> * _index.md
> * page
> * index.md
> * files
> * attachment.pdf
Be aware that if you use a multilingual website, you will need to have as many folders as languages.
That's all!
### Parameters
| Parameter | Default | Description |
|:--|:--|:--|
| title | "Attachments" | List's title |
| sort | "asc" | Sorting the output in `asc`ending or `desc`ending order |
| style | "" | Choose between `orange`, `grey`, `blue` and `green` for nice style |
| pattern | ".*" | A regular expressions, used to filter the attachments by file name. <br/><br/>The **pattern** parameter value must be [regular expressions](https://en.wikipedia.org/wiki/Regular_expression).
For example:
* To match a file suffix of 'jpg', use **.*jpg** (not *.jpg).
* To match file names ending in 'jpg' or 'png', use **.*(jpg|png)**
### Examples
#### List of attachments ending in pdf or mp4
````go
{{%/*attachments title="Related files" pattern=".*(pdf|mp4)"/*/%}}
````
renders as
{{%attachments title="Related files" pattern=".*(pdf|mp4)"/%}}
#### Colored styled box
````go
{{%/*attachments style="orange" /*/%}}
````
renders as
{{% attachments style="orange" /%}}
````go
{{%/*attachments style="grey" /*/%}}
````
renders as
{{% attachments style="grey" /%}}
````go
{{%/*attachments style="blue" /*/%}}
````
renders as
{{% attachments style="blue" /%}}
````go
{{%/*attachments style="green" /*/%}}
````
renders as
{{% attachments style="green" /%}}

View File

@ -0,0 +1 @@
Harrr, nothn' to see herre

View File

@ -0,0 +1,7 @@
+++
descrption = "Th' Attachments shorrrtcode displays a list o' files attached t' a plank"
title = "Attachments"
+++
{{% attachments /%}}
{{< piratify >}}

View File

@ -0,0 +1,16 @@
+++
description = "Nice buttons on your page"
title = "Button"
+++
A button is a just a clickable button with optional icon.
```go
{{%/* button href="https://gohugo.io/" */%}}Get Hugo{{%/* /button */%}}
{{%/* button href="https://gohugo.io/" icon="fas fa-download" */%}}Get Hugo with icon{{%/* /button */%}}
{{%/* button href="https://gohugo.io/" icon="fas fa-download" icon-position="right" */%}}Get Hugo with icon right{{%/* /button */%}}
```
{{% button href="https://gohugo.io/" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" icon="fas fa-download" %}}Get Hugo with icon{{% /button %}}
{{% button href="https://gohugo.io/" icon="fas fa-download" icon-position="right" %}}Get Hugo with icon right{{% /button %}}

View File

@ -0,0 +1,5 @@
+++
descrption = "Nice buttons on yer plank"
title = "Button"
+++
{{< piratify >}}

View File

@ -0,0 +1,51 @@
+++
alwaysopen = false
description = "List the child pages of a page"
title = "Children"
+++
Use the children shortcode to list the child pages of a page and the further descendants (children's children). By default, the shortcode displays links to the child pages.
## Usage
| Parameter | Default | Description |
|:--|:--|:--|
| page | _current_ | Specify the page name (section name) to display children for |
| containerstyle | "ul" | Choose the style used to group all children. It could be any HTML tag name |
| style | "li" | Choose the style used to display each descendant. It could be any HTML tag name |
| showhidden | "false" | When true, child pages hidden from the menu will be displayed |
| description | "false" | Allows you to include a short text under each page in the list. When no description exists for the page, children shortcode takes the first 70 words of your content. [Read more info about summaries on gohugo.io](https://gohugo.io/content/summaries/) |
| depth | 1 | Enter a number to specify the depth of descendants to display. For example, if the value is 2, the shortcode will display 2 levels of child pages. **Tips:** set 999 to get all descendants |
| sort | [ordersectionsby]({{% relref "basics/configuration#global-site-parameters" %}}) | Sort children by **weight**, to sort on menu order - **title**, to sort alphabetically on menu label. If not set it is sorted by the `ordersectionsby` setting of the site and the pages frontmatter |
## Demo
````go
{{%/* children */%}}
````
{{% children %}}
````go
{{%/* children description="true" */%}}
````
{{%children description="true" %}}
````go
{{%/* children depth="999" showhidden="true" */%}}
````
{{% children depth="999" showhidden="true" %}}
````go
{{%/* children containerstyle="div" style="h2" depth="3" description="true" */%}}
````
{{% children containerstyle="div" style="h2" depth="3" description="true" %}}
````go
{{%/* children containerstyle="div" style="div" depth="999" */%}}
````
{{% children containerstyle="div" style="div" depth="999" %}}

View File

@ -0,0 +1,6 @@
+++
alwaysopen = false
descrption = "List th' child planks on a plank"
title = "Children"
+++
{{< piratify >}}

View File

@ -0,0 +1,13 @@
+++
alwaysopen = false
description = "This is a demo child page"
tags = ["children", "non-hidden"]
title = "page 1"
weight = 10
+++
This is a demo child page.
## Subpages of this page
{{% children showhidden="true" %}}

View File

@ -0,0 +1,8 @@
+++
alwaysopen = false
descrption = "This be a demo child plank"
tags = ["children", "non-hidden"]
title = "Plank 1"
weight = 10
+++
{{< piratify >}}

View File

@ -0,0 +1,12 @@
+++
alwaysopen = false
description = "This is a demo child page"
tags = ["children", "non-hidden"]
title = "page 1-1"
+++
This is a demo child page with a hidden child. You can still access the hidden child [directly]({{% relref "shortcodes/children/children-1/children-1-1/children-1-1-1" %}}) or via the search.
## Subpages of this page
{{% children showhidden="true" %}}

View File

@ -0,0 +1,7 @@
+++
alwaysopen = false
descrption = "This be a demo child plank"
tags = ["children", "non-hidden"]
title = "Plank 1-1"
+++
{{< piratify >}}

View File

@ -0,0 +1,12 @@
+++
description = "This is a hidden demo child page"
hidden = true
tags = ["children", "hidden"]
title = "page 1-1-1 (hidden)"
+++
This is a **hidden** demo child page. This page and all its children are hidden in the menu, arrow navigation and children shortcode as long as you aren't viewing this page or its children directly.
## Subpages of this page
{{% children showhidden="true" %}}

Some files were not shown because too many files have changed in this diff Show More