docs: make installation tutorial work without making changes #801

archetypes/chapter.md

@@ -1,7 +1,7 @@
 +++
 archetype = "chapter"
 title = "{{ replace .Name "-" " " | title }}"
-weight = X
+weight = 1
 +++
 
-Lorem Ipsum.
+This is a new chapter.

archetypes/default.md

@@ -1,6 +1,5 @@
 +++
 title = "{{ replace .Name "-" " " | title }}"
-weight = X
 +++
 
-Lorem Ipsum.
+This is a new page.

archetypes/home.md

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

exampleSite/content/basics/installation/_index.en.md

@@ -6,23 +6,41 @@ 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/).
 
+{{% notice tip %}}
+The following tutorial leads you thru 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 a `new` command to create a new website.
+Hugo provides a `new` command to create a new website:
 
-```
+````shell
-hugo new site <new_project>
+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
 
+### From Download
+
+You can [download the theme as .zip](https://github.com/McShelby/hugo-theme-relearn/archive/main.zip) file and extract it into them `themes/hugo-theme-relearn` directory.
+
+### With Hugo's Module System
+
 Install the Relearn theme by following [this documentation](https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme) using Hugo's module system.
 
 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
+### Using Git or Git Submodules
-
-### From Git
 
 If you install the theme from your git repository or GitHub, you have several options.
 
@@ -32,23 +50,33 @@ Additionally you can checkout one of the tagged versions. These tagged versions
 
 Besides the usual version tags (eg `1.2.3`) there are also tags for the main version (eg. `1.2.x`), major version (eg. `1.x`) and the latest (just `x`) released version making it easier for you to pin the theme to a certain version.
 
-## Basic configuration
+## Basic Configuration
 
-When building the website, you can set a theme by using `--theme` option. However, we suggest you modify the configuration file `hugo.toml` and set the theme as the default. You can also add the `[outputs]` section to enable the [search functionality](basics/customization#activate-search).
+When building the website, you can set a theme by using `--theme` option. However, we suggest you modify the configuration file `hugo.toml` and set the theme as the default.
 
 {{< multiconfig file=hugo >}}
 theme = "hugo-theme-relearn"
-[outputs]
-home = [ "html", "rss", "search", "searchpage"]
 {{< /multiconfig >}}
 
-## Create your first chapter page
+## Create your Home 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.
+If you don't create a home page, yet, the theme will generate a placeholder text with instructions how to proceed.
+
+Start your journey by filling the home page with content
+
+````shell
+hugo new --kind home _index.md
+````
+
+By opening the given file, you should see the property `archetype=home` on top, meaning this page is a home page. The Relearn theme provides [some archetypes](cont/archetypes) to create those skeleton files for your website.
+
+Obviously you better should change the page's content.
+
+## Create your First Chapter Page
+
+Chapters are pages that contain other child pages. It has a special layout style and usually just contains the _title_ and a _brief abstract_ of the section.
 
 ````md
-### Chapter 1
-
 # Basics
 
 Discover what this Hugo theme is all about and the core concepts behind it.
@@ -58,17 +86,17 @@ renders as
 
 ![A Chapter](chapter.png?width=60pc)
 
-The Relearn theme provides archetypes to create skeletons for your website. Begin by creating your first chapter page with the following command
+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 opening the given file, you should see the property `archetype=chapter` 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.
+The `weight` number will be used to generate the subtitle of the chapter page, set the number to a consecutive value starting at 1 for each new chapter level.
 
-## Create your first content pages
+## Create your First Content Pages
 
 Then, create content pages inside the previously created chapter. Here are two ways to create content in the chapter:
 
@@ -79,7 +107,7 @@ 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
+## Launching the Website Locally
 
 Launch by using the following command:
 
@@ -91,11 +119,11 @@ 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.
+1. The home page contains some basic text.
-2. The home page explains how to customize it by following the instructions.
+2. You have a left-side **Basics** menu, containing two submenus with names equal to the `title` properties in the previously created files.
-3. When you run `hugo serve`, when the contents of the files change, the page automatically refreshes with the changes. Neat!
+3. When you run `hugo serve` your page refreshes automatically when you change a content page. Neat!
 
-## Build the website
+## Build the Website
 
 When your site is ready to deploy, run the following command:
 
@@ -103,8 +131,6 @@ When your site is ready to deploy, run the following command:
 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.
+A `public` folder will be generated, containing all content and assets for your website. It can now be deployed on any web server.
 
-{{% notice note %}}
+Now it's time to deploy your page by simply uploading your project to some webserver or by using one of [Hugo's many deployment options](https://gohugo.io/hosting-and-deployment/).
-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 %}}

exampleSite/content/cont/archetypes/_index.en.md

@@ -50,13 +50,13 @@ This leads to a file with the following content
 +++
 archetype = "chapter"
 title = "{{ replace .Name "-" " " | title }}"
-weight = X
+weight = 1
 +++
 
 Lorem Ipsum.
 ````
 
-Replace the `X` with a number. Because this number will be used to generate the subtitle of the chapter page, set the number to a consecutive value starting at 1 for each new chapter level.
+The `weight` number will be used to generate the subtitle of the chapter page, set the number to a consecutive value starting at 1 for each new chapter level.
 
 ### Default {#archetypes-default}
 
@@ -81,14 +81,11 @@ This leads to a file with the following content
 ````toml {title="*.md"}
 +++
 title = "{{ replace .Name "-" " " | title }}"
-weight = X
 +++
 
 Lorem Ipsum.
 ````
 
-Replace the `X` with a number or delete the whole `weight` parameter entirely.
-
 ## Self defined Archetypes
 
 If you are in need of further archetypes you can define your own or even redefine existing ones.