docs: finish chapter 1 #567

This commit is contained in:
Sören Weber 2024-09-23 23:12:00 +02:00
parent 58110a0c1d
commit 65023b0bec
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
15 changed files with 149 additions and 182 deletions

View file

@ -3,4 +3,4 @@ title = "{{ replace .Name "-" " " | title }}"
type = "home" type = "home"
+++ +++
This is a new home page. This is your new home page.

View file

@ -4,4 +4,4 @@ type = "chapter"
weight = 1 weight = 1
+++ +++
Discover what this Hugo theme is all about and the core-concepts behind it. Discover what this Hugo theme is all about.

View file

@ -3,7 +3,7 @@ alwaysopen = false
disableToc = false disableToc = false
title = "Changelog" title = "Changelog"
type = "changelog" type = "changelog"
weight = 4 weight = 3
+++ +++
{{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}} {{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}}

View file

@ -3,6 +3,6 @@ alwaysopen = false
disableToc = false disableToc = false
title = "Changelog" title = "Changelog"
type = "changelog" type = "changelog"
weight = 4 weight = 3
+++ +++
{{< piratify >}} {{< piratify >}}

View file

@ -1,149 +0,0 @@
+++
tags = ["documentation"]
title = "Installation"
weight = 2
+++
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/).
{{% notice tip %}}
The following tutorial leads you through the steps of creating a first, minimal new site.
You don't need to edit any files besides your `hugo.toml` and only need to execute the commands in the given order.
{{% /notice %}}
## Create your Project
Hugo provides the `new` command to create a new website:
````shell
hugo new site my-new-site
````
After that change into the directory:
````shell
cd my-new-site
````
Every upcoming command will be executed from inside your new site's root.
## Install the Theme
### Downloading as Archive
You can [download the theme as .zip archive](https://github.com/McShelby/hugo-theme-relearn/archive/main.zip) and extract its content into them `themes/hugo-theme-relearn` directory.
Afterwards add this at the end of your `hugo.toml`.
{{< multiconfig file=hugo >}}
theme = "hugo-theme-relearn"
{{< /multiconfig >}}
### Using Hugo's Module System
You can install the Relearn theme by following [the standard documentation](https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme) using Hugo's module system:
````shell
hugo mod init example.com
````
Afterwards add this at the end of your `hugo.toml`.
{{< multiconfig file=hugo >}}
[module]
[[module.imports]]
path = 'github.com/McShelby/hugo-theme-relearn'
{{< /multiconfig >}}
### Using Git Submodules
If you plan to store your project in a git repository you can create one with:
````shell
git init
````
Now add the theme as a submodule by:
````shell
git submodule add --depth 1 https://github.com/McShelby/hugo-theme-relearn.git themes/hugo-theme-relearn
````
Afterwards add this at the end of your `hugo.toml`.
{{< multiconfig file=hugo >}}
theme = "hugo-theme-relearn"
{{< /multiconfig >}}
## Create your Home Page
If you don't create a home page, yet, the theme will generate a placeholder text with instructions on how to proceed.
Start your journey by creating a home page:
````shell
hugo new --kind home _index.md
````
The newly created home page `content/_index.md` is empty and you obviously should add some meaningful content.
## Create your First Chapter Page
Chapters are meant to be top level pages that contain other child pages. They have a special layout style and often just contain the _title_ and a _brief abstract_ of the section.
Now create your first chapter page with the following command:
````shell
hugo new --kind chapter basics/_index.md
````
When opening the newly created file `content/basics/_index.md`, you should see the `weight` frontmatter with a number. This will be used to generate the subtitle of the chapter page, and should be set to a consecutive value starting at `1` for each chapter level.
## Create your First Content Pages
Then create content pages inside the previously created chapter. Here are three ways to create content in the chapter:
````shell
hugo new basics/first-content/_index.md
hugo new basics/second-content/index.md
hugo new basics/third-content.md
````
Feel free to edit those files by adding some sample content and replacing the `title` value in the beginning of the files.
{{% notice note %}}
Please note that Hugo overrides the default archetype template coming with this theme when using `hugo new site my-new-site`. To actually see your page later, you have to remove the `draft=true` from the page's frontmatter.
{{% /notice %}}
## Testing your Website Locally
Launch your new web site by using the following command:
````shell
hugo serve
````
Go to [`http://localhost:1313`](http://localhost:1313) in your browser.
You should notice a few things:
1. The home page contains your provided text.
2. You have the menu **Basics** in the sidebar. Clicking on it reveals three submenus with names equal to the `title` properties in the previously created content pages.
3. While you are running `hugo serve` your page refreshes automatically when you change a content page. Neat!
## Build and Deploy your Website
When your site is ready to be deployed, run the following command:
````shell
hugo
````
A `public` directory will be generated, containing all content and assets for your web site.
It now can be deployed to any web server by simply uploading its contents or you can check out one of [Hugo's many other deployment options](https://gohugo.io/hosting-and-deployment/).
{{% notice note %}}
If you are storing your web site in git, commit all but the `public` directory.
{{% /notice %}}

View file

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

View file

@ -0,0 +1,136 @@
+++
title = "Getting Started"
weight = 1
+++
With following steps you are initializing your new website. If you don't know Hugo, we strongly suggest you learn more about it in Hugo's great [documentation for starters](https://gohugo.io/getting-started/).
## Install Hugo
Install Hugo {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.126.0{{% /badge %}} or higher for your OS [according to the documentation](https://gohugo.io/installation/).
## Create your Project
Hugo provides the `new site` command to create a new website
````shell
hugo new site my-new-site
````
After that change into the directory
````shell
cd my-new-site
````
Every upcoming command will be executed from inside this directory.
## Install the Theme
### Downloading as Archive
You can [download the theme as .zip archive](https://github.com/McShelby/hugo-theme-relearn/archive/main.zip) and extract its content into the `themes/hugo-theme-relearn` directory.
Afterwards add this at the top of your `hugo.toml`
{{< multiconfig file=hugo >}}
theme = "hugo-theme-relearn"
{{< /multiconfig >}}
### Using with Hugo's Module System
You can install the Relearn theme following [the official documentation](https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme) using Hugo's module system
````shell
hugo mod init example.com
````
Afterwards add this at the end of your `hugo.toml`
{{< multiconfig file=hugo >}}
[module]
[[module.imports]]
path = 'github.com/McShelby/hugo-theme-relearn'
{{< /multiconfig >}}
### Using as Git Submodule
If you plan to store your project in a [Git](https://git-scm.com/) repository you can create one now with
````shell
git init
````
Now you can add the theme as a Git submodule by
````shell
git submodule add --depth 1 https://github.com/McShelby/hugo-theme-relearn.git themes/hugo-theme-relearn
````
Afterwards add this at the top of your `hugo.toml`
{{< multiconfig file=hugo >}}
theme = "hugo-theme-relearn"
{{< /multiconfig >}}
## Create your Home Page
Start your journey by creating a home page
````shell
hugo new --kind home _index.md
````
The newly created home page file `content/_index.md` is structured in two parts, the meta information of this page like the `title`, called [front matter](https://gohugo.io/content-management/front-matter/) and the text of the page itself.
## Create your First Chapter Page
Chapters are meant to be top level pages that contain other child pages. They have a special layout.
Create your first chapter page
````shell
hugo new --kind chapter basics/_index.md
````
The newly created file `content/basics/_index.md`, contains the `weight` front matter set to a number. This will be used to generate the subtitle of that chapter page, and for ordering your chapters in the menu.
## Create your First Content Pages
Now create content pages inside the previously created chapter. Here are three ways to create content in the chapter
````shell
hugo new basics/first-content/_index.md
hugo new basics/second-content/index.md
hugo new basics/third-content.md
````
Due to their file name, all three files are handled a bit differently by Hugo. You can read more about that in [Hugo's documentation](https://gohugo.io/content-management/).
Feel free to edit those files by replacing the `title` or adding an optional `weight` value in the front matter and changing the text to your liking.
## Test your Website Locally
Launch your new web site locally by using the following command
````shell
hugo serve
````
Go to [`http://localhost:1313`](http://localhost:1313) in your browser.
You can leave the web server running while editing your pages. The browser will reload automatically every time you save your files.
{{% figure src="magic.gif" link="https://gohugo.io" alt="Magic" caption="It's a kind of magic" %}}
## Build and Deploy your Website
When your site is ready to be deployed, run the following command:
````shell
hugo
````
A `public` directory will be generated, containing all content and assets for your web site.
It now can be deployed to any web server by simply uploading its contents or you can check out one of [Hugo's many other deployment options](https://gohugo.io/hosting-and-deployment/).

View file

@ -0,0 +1,5 @@
+++
title = "Gettin' started"
weight = 1
+++
{{< piratify >}}

View file

Before

Width:  |  Height:  |  Size: 1.4 MiB

After

Width:  |  Height:  |  Size: 1.4 MiB

View file

@ -3,7 +3,7 @@ alwaysopen = false
disableToc = false disableToc = false
title = "What's New" title = "What's New"
type = "releasenotes" type = "releasenotes"
weight = 3 weight = 2
+++ +++
{{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}} {{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}}

View file

@ -3,6 +3,6 @@ alwaysopen = false
disableToc = false disableToc = false
title = "What's New" title = "What's New"
type = "releasenotes" type = "releasenotes"
weight = 3 weight = 2
+++ +++
{{< piratify true >}} {{< piratify true >}}

View file

@ -1,12 +0,0 @@
+++
categories = "basic"
disableToc = true
title = "Requirements"
weight = 1
+++
Thanks to the simplicity of Hugo, this page is as empty as this theme needs requirements.
Just download at least version {{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title=" " %}}0.126.0{{% /badge %}} of the [Hugo binary](https://gohugo.io/getting-started/installing/) for your OS (Windows, Linux, Mac).
{{% figure src="magic.gif" link="https://gohugo.io" alt="Magic" caption="It's a kind of magic" %}}

View file

@ -1,7 +0,0 @@
+++
categories = "basic"
disableToc = true
title = "Requirrrements"
weight = 1
+++
{{< piratify >}}

View file

@ -4,4 +4,4 @@ type = "chapter"
weight = 2 weight = 2
+++ +++
Find out how to configure and customize the site to your liking. Find out how to configure and customize your site.

View file

@ -4,4 +4,4 @@ type = "chapter"
weight = 3 weight = 3
+++ +++
Find out how to create and organize your pages quickly and intuitively. Learn how to create and organize your content pages.