From 65023b0becc8e756c06cac5d2362baff6e9a310c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Mon, 23 Sep 2024 23:12:00 +0200 Subject: [PATCH] docs: finish chapter 1 #567 --- archetypes/home.md | 2 +- exampleSite/content/basics/_index.en.md | 2 +- .../content/basics/changelog/_index.en.md | 2 +- .../content/basics/changelog/_index.pir.md | 2 +- .../content/basics/installation/_index.en.md | 149 ------------------ .../content/basics/installation/_index.pir.md | 6 - .../content/basics/quickstart/_index.en.md | 136 ++++++++++++++++ .../content/basics/quickstart/_index.pir.md | 5 + .../{requirements => quickstart}/magic.gif | Bin .../content/basics/releasenotes/_index.en.md | 2 +- .../content/basics/releasenotes/_index.pir.md | 2 +- .../content/basics/requirements/_index.en.md | 12 -- .../content/basics/requirements/_index.pir.md | 7 - .../content/configuration/_index.en.md | 2 +- exampleSite/content/content/_index.en.md | 2 +- 15 files changed, 149 insertions(+), 182 deletions(-) delete mode 100644 exampleSite/content/basics/installation/_index.en.md delete mode 100644 exampleSite/content/basics/installation/_index.pir.md create mode 100644 exampleSite/content/basics/quickstart/_index.en.md create mode 100644 exampleSite/content/basics/quickstart/_index.pir.md rename exampleSite/content/basics/{requirements => quickstart}/magic.gif (100%) delete mode 100755 exampleSite/content/basics/requirements/_index.en.md delete mode 100644 exampleSite/content/basics/requirements/_index.pir.md diff --git a/archetypes/home.md b/archetypes/home.md index 5cbc1b0c38..05fc97d276 100644 --- a/archetypes/home.md +++ b/archetypes/home.md @@ -3,4 +3,4 @@ title = "{{ replace .Name "-" " " | title }}" type = "home" +++ -This is a new home page. +This is your new home page. diff --git a/exampleSite/content/basics/_index.en.md b/exampleSite/content/basics/_index.en.md index 290c716fc2..27bb6179f8 100755 --- a/exampleSite/content/basics/_index.en.md +++ b/exampleSite/content/basics/_index.en.md @@ -4,4 +4,4 @@ type = "chapter" weight = 1 +++ -Discover what this Hugo theme is all about and the core-concepts behind it. +Discover what this Hugo theme is all about. diff --git a/exampleSite/content/basics/changelog/_index.en.md b/exampleSite/content/basics/changelog/_index.en.md index fba89f88e2..2d474db790 100644 --- a/exampleSite/content/basics/changelog/_index.en.md +++ b/exampleSite/content/basics/changelog/_index.en.md @@ -3,7 +3,7 @@ alwaysopen = false disableToc = false title = "Changelog" type = "changelog" -weight = 4 +weight = 3 +++ {{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}} diff --git a/exampleSite/content/basics/changelog/_index.pir.md b/exampleSite/content/basics/changelog/_index.pir.md index 0a8eca85e5..781f0d23ee 100644 --- a/exampleSite/content/basics/changelog/_index.pir.md +++ b/exampleSite/content/basics/changelog/_index.pir.md @@ -3,6 +3,6 @@ alwaysopen = false disableToc = false title = "Changelog" type = "changelog" -weight = 4 +weight = 3 +++ {{< piratify >}} diff --git a/exampleSite/content/basics/installation/_index.en.md b/exampleSite/content/basics/installation/_index.en.md deleted file mode 100644 index 3860925d54..0000000000 --- a/exampleSite/content/basics/installation/_index.en.md +++ /dev/null @@ -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 %}} diff --git a/exampleSite/content/basics/installation/_index.pir.md b/exampleSite/content/basics/installation/_index.pir.md deleted file mode 100644 index a601532979..0000000000 --- a/exampleSite/content/basics/installation/_index.pir.md +++ /dev/null @@ -1,6 +0,0 @@ -+++ -tags = ["documentat'n"] -title = "Installat'n" -weight = 2 -+++ -{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/basics/quickstart/_index.en.md b/exampleSite/content/basics/quickstart/_index.en.md new file mode 100644 index 0000000000..9f1a65fcfc --- /dev/null +++ b/exampleSite/content/basics/quickstart/_index.en.md @@ -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/). diff --git a/exampleSite/content/basics/quickstart/_index.pir.md b/exampleSite/content/basics/quickstart/_index.pir.md new file mode 100644 index 0000000000..53c8ee8625 --- /dev/null +++ b/exampleSite/content/basics/quickstart/_index.pir.md @@ -0,0 +1,5 @@ ++++ +title = "Gettin' started" +weight = 1 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/basics/requirements/magic.gif b/exampleSite/content/basics/quickstart/magic.gif similarity index 100% rename from exampleSite/content/basics/requirements/magic.gif rename to exampleSite/content/basics/quickstart/magic.gif diff --git a/exampleSite/content/basics/releasenotes/_index.en.md b/exampleSite/content/basics/releasenotes/_index.en.md index 5c2ee48ffa..f4a74eecba 100644 --- a/exampleSite/content/basics/releasenotes/_index.en.md +++ b/exampleSite/content/basics/releasenotes/_index.en.md @@ -3,7 +3,7 @@ alwaysopen = false disableToc = false title = "What's New" type = "releasenotes" -weight = 3 +weight = 2 +++ {{% pages showdivider="true" showhidden="true" hidevisible="true" showtitle="true" %}} diff --git a/exampleSite/content/basics/releasenotes/_index.pir.md b/exampleSite/content/basics/releasenotes/_index.pir.md index 7f8cff8d07..4d0f746fc4 100644 --- a/exampleSite/content/basics/releasenotes/_index.pir.md +++ b/exampleSite/content/basics/releasenotes/_index.pir.md @@ -3,6 +3,6 @@ alwaysopen = false disableToc = false title = "What's New" type = "releasenotes" -weight = 3 +weight = 2 +++ {{< piratify true >}} \ No newline at end of file diff --git a/exampleSite/content/basics/requirements/_index.en.md b/exampleSite/content/basics/requirements/_index.en.md deleted file mode 100755 index fb25b56350..0000000000 --- a/exampleSite/content/basics/requirements/_index.en.md +++ /dev/null @@ -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" %}} diff --git a/exampleSite/content/basics/requirements/_index.pir.md b/exampleSite/content/basics/requirements/_index.pir.md deleted file mode 100644 index 187b702c32..0000000000 --- a/exampleSite/content/basics/requirements/_index.pir.md +++ /dev/null @@ -1,7 +0,0 @@ -+++ -categories = "basic" -disableToc = true -title = "Requirrrements" -weight = 1 -+++ -{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/configuration/_index.en.md b/exampleSite/content/configuration/_index.en.md index 21d905f73f..fe72b7820b 100644 --- a/exampleSite/content/configuration/_index.en.md +++ b/exampleSite/content/configuration/_index.en.md @@ -4,4 +4,4 @@ type = "chapter" weight = 2 +++ -Find out how to configure and customize the site to your liking. +Find out how to configure and customize your site. diff --git a/exampleSite/content/content/_index.en.md b/exampleSite/content/content/_index.en.md index 8d6ba39df9..a0bad6ade4 100644 --- a/exampleSite/content/content/_index.en.md +++ b/exampleSite/content/content/_index.en.md @@ -4,4 +4,4 @@ type = "chapter" weight = 3 +++ -Find out how to create and organize your pages quickly and intuitively. +Learn how to create and organize your content pages.