Theme fest ins Repo uebernehmen statt als Submodule
Ein normaler git clone holt Submodules nicht mit - geprueft: nach dem Klonen des Repos war themes/gokarna leer. Portainer klont ebenso, der Build im Container waere also an dem fehlenden Theme gescheitert. Gokarna liegt jetzt direkt im Repo, festgeschrieben auf Commit 8306042, den Stand, mit dem die Seite bisher gebaut wurde. .gitmodules entfaellt. Nachteil: Theme-Updates muessen kuenftig von Hand eingespielt werden. Dafuer baut das Repo aus jedem beliebigen Klon heraus, ohne Sonderbehandlung. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,345 @@
|
||||
---
|
||||
weight: 10
|
||||
title: "Theme Documentation - Basics"
|
||||
date: 2020-03-06T21:29:01+08:00
|
||||
description: "A guide to getting started with Gokarna"
|
||||
tags: ["installation", "configuration", "markdown"]
|
||||
type: post
|
||||
showTableOfContents: true
|
||||
---
|
||||
|
||||
Gokarna is an opinionated theme with a focus on minimalism and simplicity.
|
||||
|
||||
## Installation
|
||||
|
||||
Follow these steps to initialize your new website.
|
||||
|
||||
If you are new to [Hugo](https://gohugo.io/), we suggest following this [great documentation for beginners](https://gohugo.io/getting-started/quick-start/).
|
||||
|
||||
### a. Create Your Project {#create-your-project}
|
||||
|
||||
Hugo provides a `new` subcommand to create a new website:
|
||||
|
||||
```bash
|
||||
hugo new site my-website
|
||||
cd my-website
|
||||
```
|
||||
|
||||
### b. Install the Theme {#install-the-theme}
|
||||
|
||||
The theme's repository is: [https://github.com/gokarna-theme/gokarna-hugo](https://github.com/gokarna-theme/gokarna-hugo).
|
||||
|
||||
Make this repository a submodule of your Git project:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git submodule add https://github.com/gokarna-theme/gokarna-hugo.git themes/gokarna
|
||||
```
|
||||
|
||||
### c. Basic Configuration {#basic-configuration}
|
||||
|
||||
A simple Hugo [configuration file](https://gohugo.io/getting-started/configuration/#configuration-file) with [menu items](https://gohugo.io/content-management/menus/#properties-front-matter).
|
||||
|
||||
Gokarna supports [adding Feather icons to the header](/posts/theme-documentation-advanced/#icons-in-header).
|
||||
|
||||
```toml
|
||||
baseURL = "https://example.org/"
|
||||
defaultContentLanguage = "en"
|
||||
# Automatically generate robots.txt
|
||||
enableRobotsTXT = true
|
||||
languageCode = "en"
|
||||
theme = "gokarna"
|
||||
title = "My New Hugo Site"
|
||||
|
||||
[menu]
|
||||
[[menu.main]]
|
||||
# Display name
|
||||
name = "Posts"
|
||||
|
||||
# Relative URL slug (appended to baseURL)
|
||||
url = "/posts/"
|
||||
|
||||
# Lower weights are listed first in the menu (leftmost); higher weights are
|
||||
# listed last in the menu (rightmost)
|
||||
weight = 1
|
||||
|
||||
[[menu.main]]
|
||||
name = "Tags"
|
||||
url = "/tags/"
|
||||
weight = 2
|
||||
|
||||
[[menu.main]]
|
||||
# Unique identifiers are required for menu entries without a name property,
|
||||
# or for menu entries which re-use a name
|
||||
identifier = "github"
|
||||
|
||||
# Absolute URL to external resource
|
||||
url = "https://github.com"
|
||||
weight = 3
|
||||
|
||||
# Surround the menu entry (or name) with HTML content, such as Feather
|
||||
# icons: https://feathericons.com
|
||||
pre = "<span data-feather='github'></span>"
|
||||
post = ""
|
||||
```
|
||||
|
||||
|
||||
### d. Create Your First Post {#create-your-first-post}
|
||||
|
||||
Use the [`new` subcommand](https://gohugo.io/commands/hugo_new/#hugo-new) to create a post (in [the `content/` directory](https://gohugo.io/content-management/organization/#organization-of-content-source)):
|
||||
|
||||
```bash
|
||||
hugo new posts/'My First Post'.md
|
||||
```
|
||||
|
||||
Two [content types](https://gohugo.io/content-management/types/) are supported in Gokarna:
|
||||
|
||||
1. `type: "post"`
|
||||
|
||||
A blog post consisting of a [page title](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title#page_titles_and_seo), [meta description](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML#adding_an_author_and_description), creation/last modified dates, [SEO keywords (tags)](/posts/theme-documentation-advanced/#seo-keywords), and Markdown content.
|
||||
|
||||
Read more about Posts in the [advanced documentation](/posts/theme-documentation-advanced/#post).
|
||||
|
||||
2. `type: "page"`
|
||||
|
||||
A standalone page which only renders Markdown. Best used for custom pages (e.g. your [portfolio](/projects/)) which should not feature in your [Posts](/posts/) timeline.
|
||||
|
||||
Read more about Pages in the [advanced documentation](/posts/theme-documentation-advanced/#page).
|
||||
|
||||
#### Using archetypes
|
||||
|
||||
`hugo new` will automatically use an appropriate [archetype](https://gohugo.io/content-management/archetypes/#lookup-order) (see [`archetypes/`](https://github.com/gokarna-theme/gokarna-hugo/tree/main/archetypes)) and insert [front matter](https://gohugo.io/content-management/front-matter/) depending on the location of your content:
|
||||
|
||||
- `hugo new posts/$post-name.md` automatically sets `type: "post"`
|
||||
- `hugo new $page-name.md` automatically sets `type: "page"`
|
||||
|
||||
Gokarna employs [custom front matter](/posts/theme-documentation-advanced/#content-types), which is included in the archetypes:
|
||||
|
||||
- The creation date of the file is automatically set (e.g. `date: 2023-12-25`)
|
||||
- The file name is used as the default title (e.g. `title: "My First Post"`)
|
||||
|
||||
### e. Launching the Website Locally {#launching-the-website-locally}
|
||||
|
||||
Use the [`server` subcommand](https://gohugo.io/commands/hugo_server/#synopsis) to view your site.
|
||||
|
||||
```bash
|
||||
hugo server
|
||||
```
|
||||
|
||||
Go to [`http://localhost:1313`](http://localhost:1313/) (if no other Hugo servers are running; Hugo will use an [ephemeral port](https://en.wikipedia.org/wiki/Ephemeral_port) if one or more servers are running concurrently on the host).
|
||||
|
||||
### f. Build the Website {#build-the-website}
|
||||
|
||||
Use the `hugo` command to build your site.
|
||||
|
||||
```bash
|
||||
hugo
|
||||
```
|
||||
|
||||
A `public` folder will be generated, containing all static content and assets for your website. It can be hosted on any web server.
|
||||
|
||||
The website can be automatically published and hosted with [Netlify](https://www.netlify.com/), [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [GitHub Pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/), and more...
|
||||
|
||||
## Configuration
|
||||
|
||||
In addition to [Hugo global configuration](https://gohugo.io/overview/configuration/) and [menu configuration](#basic-configuration), Gokarna lets you define the following [parameters](https://gohugo.io/methods/site/params/) in your site configuration.
|
||||
|
||||
See this sample `hugo.toml`, which uses Gokarna's default values, and [exampleSite's `hugo.toml`](https://github.com/gokarna-theme/gokarna-hugo/blob/main/exampleSite/hugo.toml):
|
||||
|
||||
```toml
|
||||
[params]
|
||||
# Choose the color shown when hyperlinks are hovered over
|
||||
accentColor = "#FF4D4D"
|
||||
|
||||
# Resource URL for the site avatar (home page and header)
|
||||
avatarURL = "/images/avatar.webp"
|
||||
|
||||
# Describe the avatar for screen readers
|
||||
avatarAltText = "avatar"
|
||||
|
||||
# Set the avatar's size: size-xs, size-s, size-m, size-l & size-xl
|
||||
avatarSize = "size-m"
|
||||
|
||||
# Inject arbitrary HTML via the <head> tag
|
||||
# Best used for importing custom JavaScript, CSS, or analytics
|
||||
customHeadHTML = ""
|
||||
|
||||
# Configure how post dates are displayed
|
||||
dateFormat = "January 2, 2006"
|
||||
|
||||
# Home page meta description
|
||||
description = "Sky above, sand below & peace within"
|
||||
|
||||
# Footer text (i.e. author/project name)
|
||||
footer = "The Marauders"
|
||||
|
||||
# Define SEO keywords
|
||||
metaKeywords = ["blog", "gokarna", "hugo"]
|
||||
|
||||
# Define how many posts are displayed on the home page
|
||||
# showPostsOnHomePage must be "popular" or "recent"
|
||||
numberPostsOnHomePage = 4
|
||||
|
||||
# Display a "back to top" button on posts and pages: true, false
|
||||
# May not render on smaller screen sizes
|
||||
showBackToTopButton = true
|
||||
|
||||
# Display posts on the home page:
|
||||
# "popular" (order posts by weight)
|
||||
# "recent" (order posts by date)
|
||||
# "", unset (do not display)
|
||||
showPostsOnHomePage = ""
|
||||
|
||||
# Show the previous and next post in your timeline: "true", "false"
|
||||
# Incompatible with Weight
|
||||
togglePreviousAndNextButtons = false
|
||||
```
|
||||
|
||||
### Accent color
|
||||
|
||||
The color displayed when a user hovers over hyperlinks (`<a>` tags), expressed as a [hexadecimal](https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color).
|
||||
|
||||
```toml
|
||||
[params]
|
||||
accentColor = "#FF4D4D"
|
||||
```
|
||||
|
||||
### Avatar URL
|
||||
|
||||
The avatar's resource URL, displayed on the [home page](/) and header (top-left).
|
||||
|
||||
Images are typically placed into the [`assets/`](https://gohugo.io/getting-started/directory-structure/#assets) or [`static/`](https://gohugo.io/getting-started/directory-structure/#static) directories (which are copied to the top-level directory [at build time](#build-the-website)).
|
||||
|
||||
```toml
|
||||
[params]
|
||||
avatarURL = "/images/avatar.webp"
|
||||
```
|
||||
|
||||
### Avatar size
|
||||
|
||||
Set the avatar's size as: `size-xs`, `size-s`, `size-m`, `size-l`, or `size-xl`.
|
||||
|
||||
```toml
|
||||
[params]
|
||||
avatarSize = "size-m"
|
||||
```
|
||||
|
||||
### Custom Head HTML
|
||||
|
||||
Add arbitrary HTML code to the [`<head>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head).
|
||||
|
||||
```toml
|
||||
[params]
|
||||
customHeadHTML = "<script>console.log('Any HTML')</script>"
|
||||
```
|
||||
|
||||
Examples are available in the [advanced documentation](/posts/theme-documentation-advanced/#bring-your-own-scripts).
|
||||
|
||||
### Date format
|
||||
|
||||
[Configure how posts date are displayed](https://gohugo.io/functions/time/format/), using [date strings](https://pkg.go.dev/time#pkg-constants).
|
||||
|
||||
```toml
|
||||
[params]
|
||||
dateFormat = "2 January, 2006"
|
||||
```
|
||||
|
||||
### Description
|
||||
|
||||
[Meta description](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML#adding_an_author_and_description) to display on the home page, below the title and avatar.
|
||||
|
||||
```toml
|
||||
[params]
|
||||
description = "Sky above, sand below & peace within"
|
||||
```
|
||||
|
||||
### Display content on the home page
|
||||
|
||||
Markdown content in `content/_index.md` will be rendered on the home page, below the social icons.
|
||||
|
||||
### Display posts on the home page
|
||||
|
||||
Recent and popular posts can be shown on the home page:
|
||||
|
||||
- `popular`: Sort posts in ascending order of their [Weight](https://gohugo.io/methods/page/weight/)
|
||||
|
||||
**If any post on your site defines `weight`, you cannot enable [Previous and Next buttons](#previous-and-next-buttons).**
|
||||
|
||||
- `recent`: Sort posts in ascending order of [Date](https://gohugo.io/methods/page/date/)
|
||||
|
||||
- Do not show anything if the variable is:
|
||||
- unset
|
||||
- an empty string (`""`)
|
||||
|
||||
The number of posts displayed on the home page can be changed by setting `numberPostsOnHomePage`. If `numberPostsOnHomePage` is equal to `""` or `0`, the default value (`4`) is used.
|
||||
|
||||
```toml
|
||||
[params]
|
||||
showPostsOnHomePage = ""
|
||||
numberPostsOnHomePage = 4
|
||||
```
|
||||
|
||||
### Favicons
|
||||
|
||||
Place favicons into the `static/` directory. The following files are supported:
|
||||
|
||||
- `apple-touch-icon.png` (180x180)
|
||||
- `favicon-32x32.png` (32x32)
|
||||
- `favicon-16x16.png` (16x16)
|
||||
- `mstile-150x150.png` (150x150)
|
||||
- `android-chrome-192x192.png` (192x192)
|
||||
- `android-chrome-512x512.png` (512x512)
|
||||
|
||||
Favicons can be generated using services such as [favicon.io](https://favicon.io), or [realfavicongenerator.net](https://realfavicongenerator.net/).
|
||||
|
||||
### Font size
|
||||
|
||||
Set the content [`font-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size).
|
||||
|
||||
Note that '[defining font sizes in px is not accessible](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size#pixels)'.
|
||||
|
||||
```toml
|
||||
[params]
|
||||
fontSize = "1.1rem" # equal to 17.6px
|
||||
```
|
||||
|
||||
### Footer
|
||||
|
||||
Text to display in the footer section, typically the name of the author or project.
|
||||
|
||||
```toml
|
||||
[params]
|
||||
footer = "The Marauders"
|
||||
```
|
||||
|
||||
`footer` can include [Markdown syntax](https://www.markdownguide.org/tools/hugo/) - best used for including hyperlinks, emoji, or text formatting.
|
||||
|
||||
### Previous and Next buttons
|
||||
|
||||
At the bottom of a post, show the previous and next post chronologically.
|
||||
|
||||
**Warning**: Not compatible with the `.Weight` parameter.
|
||||
|
||||
If any post front matter contains `weight`, the posts will not appear by Date. See [Hugo's default sort](https://gohugo.io/templates/lists#default-weight--date--linktitle--filepath).
|
||||
|
||||
```toml
|
||||
[params]
|
||||
togglePreviousAndNextButtons = false
|
||||
```
|
||||
|
||||
### Reading time
|
||||
|
||||
Display a post's [estimated reading time](https://gohugo.io/methods/page/readingtime/) in minutes.
|
||||
|
||||
```toml
|
||||
[params]
|
||||
displayReadingTime = false
|
||||
```
|
||||
|
||||
### robots.txt
|
||||
|
||||
[Automatically generate](https://gohugo.io/templates/robots/) a `robots.txt` file, used to ['manage crawler traffic to your site'](https://developers.google.com/search/docs/crawling-indexing/robots/intro).
|
||||
|
||||
```toml
|
||||
enableRobotsTXT = true
|
||||
```
|
||||
Reference in New Issue
Block a user