My instructions to get v0.5 working for beginners: New (Books) menu and code syntax highlight

[StefanSalewski]

Instructions for Hugo theme doks 0.5 to add a new Menu and
to ensure that custom code syntax highlight works:

First, follow the instructions in https://getdoks.org/docs/tutorial/introduction/

These notes are for Starter theme with git clone https://github.com/h-enk/doks.git my-doks-site

Important is, that we have to copy layouts for new entries.
And note that commands like "npm run create" will create index files
with frontmatter draft set to true, so they will be not shown.

cd layouts/
cp -r docs/ books/
cd ../content/en/
mkdir books
npm run create books/_index.md
mkdir books/allbooks
npm run create books/allbooks/index.md

set draft to false in books/_index.md
set draft to false in books/allbooks/index.md
add some markdown text to books/allbooks/index.md
edit ./config/_default/menus/menus.en.toml
maybe add
[[main]]
name = "Books"
url = "/books/allbooks/"
weight = 10

And we are done, we have a new Books entry.

Making syntax highlighting work

Edit ./assets/js/highlight.js

Add missing language like
import nim from 'highlight.js/lib/languages/nim';
hljs.registerLanguage('nim', nim);

edit content/en/books/allbooks/index.md, and add something like

{{< highlight nim >}}
import std/strformat

type
Person = object
name: string
age: Natural # Ensures the age is positive

let people = [
Person(name: "John", age: 45),
Person(name: "Kate", age: 30)
]

for person in people:

Type-safe string interpolation,

evaluated at compile time.

echo(fmt"{person.name} is {person.age} years old")

{{< / highlight >}}

Optionally select a highlight style:

edit ./assets/scss/app.scss

Uncomment and change line
// @import "highlight.js/scss/github-dark-dimmed";

@import "highlight.js/scss/monokai";

and comment out
//@import "components/syntax";

And we should be done.

[StefanSalewski]

Actually, following https://getdoks.org/docs/overview/commands/

For example, create a docs based tree named guides:

npm run create -- --kind docs guides

copying layouts/docs seems to be not needed. The trick seems to be that generated frontmatters of index files have a type field like

npm run create -- --kind docs tutorials

cat tutorials/_index.md 
---
title: "Docs"
description: ""
lead: ""
date: 2022-01-25T14:40:56+01:00
lastmod: 2022-01-25T14:40:56+01:00
draft: false
images: []
type: docs
---

Is title: "Docs" right?

[h-enk]

copying layouts/docs seems to be not needed. The trick seems to be that generated frontmatters of index files have a type field like

That's correct. Only if you want to have a different layout, you would have to copy, paste, and customize.

Is title: "Docs" right?

Yes, you should update this

[h-enk]

Made it flexible /automatic in Doks 1.0:

title: "{{ .Name }}"

[h-enk]

See #395 (comment)