diff --git a/.gitignore b/.gitignore index eebcb0a..db5a768 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,6 @@ exampleSite/public/ .DS_Store .hugo_build.lock .obsidian +.vscode +.zed resources/ diff --git a/README.md b/README.md index faa9573..a30fe37 100644 --- a/README.md +++ b/README.md @@ -235,7 +235,7 @@ bookHref = '' bookIcon = 'calendar' ``` -### Partials +## Partials There are layout partials available for you to easily override components of the theme in `layouts/partials/`. @@ -253,7 +253,7 @@ In addition to this, there are several empty partials you can override to easily | `layouts/partials/docs/inject/toc-before.html` | At the beginning of table of contents block | | `layouts/partials/docs/inject/toc-after.html` | At the end of table of contents block | -### Extra Customisation +## Extra Customisation | File | Description | | ------------------------ | ------------------------------------------------------------------------------------- | @@ -264,7 +264,7 @@ In addition to this, there are several empty partials you can override to easily | `assets/mermaid.json` | Replace Mermaid initialization config | | `assets/katex.json` | Replace KaTeX initialization config | -### Plugins +## Plugins There are a few features implemented as pluggable `scss` styles. Usually these are features that don't make it to the core but can still be useful. @@ -276,7 +276,7 @@ There are a few features implemented as pluggable `scss` styles. Usually these a To enable plugins, add `@import "plugins/{name}";` to `assets/_custom.scss` in your website root. -### Hugo Internal Templates +## Hugo Internal Templates There are a few hugo templates inserted in `` @@ -289,6 +289,15 @@ In fact almost empty not quite empty because an empty file looks like absent for ``` +## Special layouts + +There are extra page layouts apart from documentation pages, to apply set `layout: {name}` in page frontmatter + +| Layout | Description | +| --------------------------------- | ------------ | +| `landing` | Renders a langing/home page, hides side menus and adds home menu at the top | +| `book` | Renders a single-page with all pages in configured BookSection section | + ## Shortcodes - [Buttons](https://hugo-book-demo.netlify.app/docs/shortcodes/buttons/) diff --git a/assets/_markdown.scss b/assets/_markdown.scss index 483db8c..19939f7 100644 --- a/assets/_markdown.scss +++ b/assets/_markdown.scss @@ -4,7 +4,7 @@ line-height: 1.6; // remove padding at the beginning of page - > :first-child { + >:first-child, >section:first-child :first-child { margin-top: 0; } diff --git a/assets/_shortcodes.scss b/assets/_shortcodes.scss index 1af4458..2c686c5 100644 --- a/assets/_shortcodes.scss +++ b/assets/_shortcodes.scss @@ -222,15 +222,6 @@ margin: $padding-16 0; } - .book-hero { - min-height: $padding-16 * 24; - align-content: center; - - h1 { - font-size: 3em; - } - } - .book-codeblock-filename { background: var(--gray-100); border: $padding-1 solid var(--gray-200); diff --git a/assets/icons/markdown.svg b/assets/icons/markdown.svg new file mode 100644 index 0000000..1a0c0d8 --- /dev/null +++ b/assets/icons/markdown.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/exampleSite/assets/_custom.scss b/exampleSite/assets/_custom.scss index 79b1866..e6d6dcf 100644 --- a/exampleSite/assets/_custom.scss +++ b/exampleSite/assets/_custom.scss @@ -4,4 +4,13 @@ // @import "plugins/scrollbars"; // @import "plugins/themes"; -@import "plugins/themes"; \ No newline at end of file +@import "plugins/themes"; + +.book-hero { + min-height: $padding-16 * 24; + align-content: center; + + h1 { + font-size: 3em; + } +} \ No newline at end of file diff --git a/exampleSite/content.en/book/index.md b/exampleSite/content.en/book/index.md new file mode 100644 index 0000000..43f90c7 --- /dev/null +++ b/exampleSite/content.en/book/index.md @@ -0,0 +1,7 @@ +--- +title: Single Page +layout: book +menu: + after: + weight: 7 +--- diff --git a/exampleSite/content.en/docs/shortcodes/tests.md b/exampleSite/content.en/docs/shortcodes/tests.md index 7f61481..7ffa3fd 100644 --- a/exampleSite/content.en/docs/shortcodes/tests.md +++ b/exampleSite/content.en/docs/shortcodes/tests.md @@ -17,7 +17,7 @@ bookHidden: true {{}} - ## Card - {{}} + {{}} **Markdown** Suspendisse sed congue orci, eu congue metus. Nullam feugiat urna massa. {{}} diff --git a/exampleSite/content.en/posts/_index.md b/exampleSite/content.en/posts/_index.md index 996c430..369daa2 100644 --- a/exampleSite/content.en/posts/_index.md +++ b/exampleSite/content.en/posts/_index.md @@ -1,6 +1,6 @@ --- +title: Blog menu: after: weight: 5 -title: Blog --- diff --git a/exampleSite/content.he/docs/_index.md b/exampleSite/content.he/docs/_index.md new file mode 100644 index 0000000..e69de29 diff --git a/exampleSite/content.zh/docs/_index.md b/exampleSite/content.zh/docs/_index.md new file mode 100644 index 0000000..e69de29 diff --git a/exampleSite/hugo.toml b/exampleSite/hugo.toml index 2d98f1c..deead31 100644 --- a/exampleSite/hugo.toml +++ b/exampleSite/hugo.toml @@ -14,6 +14,17 @@ copyright = '[© CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcod disablePathToLower = true enableGitInfo = true +[outputFormats] +[outputFormats.txt] + mediaType = 'text/plain' + baseName = 'source' + isPlainText = true + +[outputs] + home = ['html', 'txt', 'rss'] + page = ['html', 'txt'] + section = ['html', 'txt'] + # Needed for mermaid/katex shortcodes [markup] [markup.goldmark.renderer] diff --git a/exampleSite/hugo.yaml b/exampleSite/hugo.yaml index 6f2df14..cdd036e 100644 --- a/exampleSite/hugo.yaml +++ b/exampleSite/hugo.yaml @@ -14,6 +14,16 @@ copyright: "[© CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode disablePathToLower: true enableGitInfo: true +outputFormats: + txt: + mediaType: "text/plain" + baseName: "source" + isPlainText: true +outputs: + home: ["html", "txt", "rss"] + page: ["html", "txt"] + section: ["html", "txt"] + # Needed for mermaid/katex shortcodes markup: goldmark: @@ -97,12 +107,12 @@ params: # (Optional, default none) Set template for commit link for the page. Requires enableGitInfo. # When set enabled 'Last Modified' and a link to the commit in the footer of the page. # Param is executed as template using .Site, .Page and .GitInfo as context. - BookLastChangeLink: 'https://github.com/alex-shpak/hugo-book/commit/{{ .GitInfo.Hash }}' + BookLastChangeLink: "https://github.com/alex-shpak/hugo-book/commit/{{ .GitInfo.Hash }}" # (Optional, default none) Set template for edit page link. # When set enabled 'Edit this page' link in the footer of the page. # Param is executed as template using .Site, .Page and .Path as context. - BookEditLink: 'https://github.com/alex-shpak/hugo-book/edit/main/exampleSite/{{ .Path }}' + BookEditLink: "https://github.com/alex-shpak/hugo-book/edit/main/exampleSite/{{ .Path }}" # (Optional, default 'January 2, 2006') Configure the date format used on the pages # - In git information @@ -126,7 +136,7 @@ params: # Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode # Hugo Book will print warning or error if page referenced in markdown does not exists. # Possible values are false | 'warning' | 'error' - BookPortableLinks: 'warning' + BookPortableLinks: "warning" # /!\ This is an experimental feature, might be removed or changed at any time # (Optional, experimental, default false) diff --git a/layouts/_partials/docs/brand.html b/layouts/_partials/docs/brand.html index 26d0a5c..cd3ed50 100644 --- a/layouts/_partials/docs/brand.html +++ b/layouts/_partials/docs/brand.html @@ -1,5 +1,5 @@

- + {{- with .Site.Params.BookLogo -}} {{ partial {{- end -}} diff --git a/layouts/_partials/docs/comments.html b/layouts/_partials/docs/comments.html index aecf183..fc97d15 100644 --- a/layouts/_partials/docs/comments.html +++ b/layouts/_partials/docs/comments.html @@ -1,2 +1,2 @@ - +{{/* This partial can be replaced to support other commenting engines */}} {{ partial "disqus.html" . }} diff --git a/layouts/_partials/docs/date.html b/layouts/_partials/docs/date.html index 8c75361..fcaca2c 100644 --- a/layouts/_partials/docs/date.html +++ b/layouts/_partials/docs/date.html @@ -1,6 +1,6 @@ - +*/}} {{- $format := default "January 2, 2006" .Format -}} {{- return (time.Format $format .Date) -}} diff --git a/layouts/_partials/docs/footer.html b/layouts/_partials/docs/footer.html index dd5b7d0..a298c60 100644 --- a/layouts/_partials/docs/footer.html +++ b/layouts/_partials/docs/footer.html @@ -10,6 +10,15 @@ {{ end }} +
+{{ with .OutputFormats.Get "txt" }} + + {{ partial + {{ partial "docs/text/i18n" "Source" }} + +{{ end }} +
+
{{ if and .File .Site.Params.BookEditLink }} diff --git a/layouts/_partials/docs/html-head.html b/layouts/_partials/docs/html-head.html index 62156db..e1b007d 100644 --- a/layouts/_partials/docs/html-head.html +++ b/layouts/_partials/docs/html-head.html @@ -47,9 +47,8 @@ https://github.com/alex-shpak/hugo-book {{ partial "google_analytics.html" . }} - -{{- with .OutputFormats.Get "rss" -}} - {{ printf `` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} +{{- range .AlternativeOutputFormats -}} + {{ printf `` .Rel .MediaType.Type .Permalink $.Title | safeHTML }} {{ end -}} {{- define "integrity" -}} diff --git a/layouts/_partials/docs/links/home.html b/layouts/_partials/docs/links/home.html new file mode 100644 index 0000000..d45e3fc --- /dev/null +++ b/layouts/_partials/docs/links/home.html @@ -0,0 +1 @@ +{{ return cond (not .Site.Home.File) hugo.Sites.Default.Home.RelPermalink .Site.Home.RelPermalink }} \ No newline at end of file diff --git a/layouts/_partials/docs/menu-filetree.html b/layouts/_partials/docs/menu-filetree.html index 8bbbe4c..c8f3d03 100644 --- a/layouts/_partials/docs/menu-filetree.html +++ b/layouts/_partials/docs/menu-filetree.html @@ -1,9 +1,4 @@ -{{ $bookSection := default "docs" .Site.Params.BookSection }} -{{ if eq $bookSection "*" }} - {{ $bookSection = "/" }}{{/* Backward compatibility */}} -{{ end }} - -{{ with .Site.GetPage $bookSection }} +{{ with (partialCached "docs/menu-section" .Site) }} {{ template "book-section-children" (dict "Section" . "CurrentPage" $) }} {{ end }} diff --git a/layouts/_partials/docs/menu-hugo.html b/layouts/_partials/docs/menu-hugo.html index 7e22139..2f9bdff 100644 --- a/layouts/_partials/docs/menu-hugo.html +++ b/layouts/_partials/docs/menu-hugo.html @@ -1,7 +1,7 @@ - +*/}} {{- if .Menu -}} {{- template "book-menu-hugo" . -}} {{- end -}} diff --git a/layouts/_partials/docs/menu-section-pages.html b/layouts/_partials/docs/menu-section-pages.html new file mode 100644 index 0000000..e283166 --- /dev/null +++ b/layouts/_partials/docs/menu-section-pages.html @@ -0,0 +1,16 @@ +{{/* Recursively creates a slice of pages under given page */}} + +{{ define "book-menu-recurse" }} + {{ if not .Page.Params.BookHidden }} + {{ if .Page.Content }} + {{ .Scratch.Add "BookPages" (slice .Page) }} + {{ end }} + {{ range .Page.Pages }} + {{ template "book-menu-recurse" (dict "Scratch" $.Scratch "Page" .) }} + {{ end }} + {{ end }} +{{ end }} + +{{ $scratch := newScratch }} +{{ template "book-menu-recurse" (dict "Scratch" $scratch "Page" .) }} +{{ return $scratch.Get "BookPages" }} diff --git a/layouts/_partials/docs/menu-section.html b/layouts/_partials/docs/menu-section.html new file mode 100644 index 0000000..24df7be --- /dev/null +++ b/layouts/_partials/docs/menu-section.html @@ -0,0 +1,8 @@ +{{/* returns the section to be rendered as menu */}} +{{ $bookSection := default "docs" .Params.BookSection }} +{{ $section := .GetPage (cond (eq $bookSection "*") "/" $bookSection) }} +{{ if $section }} + {{ return $section }} +{{ else }} + {{ errorf "%s: Section '%s' not found, check BookSection theme parameter" $ $bookSection }} +{{ end }} diff --git a/layouts/_partials/docs/prev-next-cache.html b/layouts/_partials/docs/prev-next-cache.html deleted file mode 100644 index 1561c06..0000000 --- a/layouts/_partials/docs/prev-next-cache.html +++ /dev/null @@ -1,14 +0,0 @@ -{{ $scratch := newScratch }} -{{ template "recurse" (dict "Scratch" $scratch "Sections" .) }} -{{ define "recurse" }} - {{ range .Sections }} - {{ if and .Content (not .Params.BookHidden) }} - {{ $.Scratch.Add "BookPages" (slice .) }} - {{ end }} - {{ if .IsSection }} - {{ template "recurse" (dict "Scratch" $.Scratch "Sections" .Pages) }} - {{ end }} - {{ end }} -{{ end }} - -{{ return $scratch.Get "BookPages" }} diff --git a/layouts/_partials/docs/prev-next.html b/layouts/_partials/docs/prev-next.html index 620bbe7..166eb3a 100644 --- a/layouts/_partials/docs/prev-next.html +++ b/layouts/_partials/docs/prev-next.html @@ -1,14 +1,9 @@ -{{ $bookSection := default "docs" .Site.Params.BookSection }} -{{ if eq $bookSection "*" }} - {{ $bookSection = "/" }}{{/* Backward compatibility */}} -{{ end }} +{{- with (partialCached "docs/menu-section" .Site) -}} + {{- $pages := partialCached "docs/menu-section-pages" . -}} + {{- $prev := $pages.Next $ -}} + {{- $next := $pages.Prev $ -}} -{{ with .Site.GetPage $bookSection }} - {{ $pages := partialCached "docs/prev-next-cache" .Pages }} - {{ $prev := $pages.Next $ }} - {{ $next := $pages.Prev $ }} - - {{- if or $prev $next }} + {{- if or $prev $next -}}
{{ with $prev }} @@ -27,5 +22,5 @@ {{ end }}
- {{ end -}} -{{ end }} + {{- end -}} +{{- end -}} diff --git a/layouts/_partials/docs/text/template.html b/layouts/_partials/docs/text/template.html index 53e535d..7fd3685 100644 --- a/layouts/_partials/docs/text/template.html +++ b/layouts/_partials/docs/text/template.html @@ -1,8 +1,7 @@ - - +*/}} {{- $checksum := . | encoding.Jsonify | crypto.SHA1 | printf "book-%s" -}} {{- $template := resources.FromString $checksum .Template -}} {{- $template = $template | resources.ExecuteAsTemplate $checksum .Context -}} diff --git a/layouts/_partials/docs/title.html b/layouts/_partials/docs/title.html index 83df5b6..a7ee61d 100644 --- a/layouts/_partials/docs/title.html +++ b/layouts/_partials/docs/title.html @@ -1,7 +1,7 @@ - +*/}} {{ $title := "" }} {{ if .LinkTitle }} diff --git a/layouts/_partials/docs/toc-show.html b/layouts/_partials/docs/toc-show.html index d54c312..5cb882f 100644 --- a/layouts/_partials/docs/toc-show.html +++ b/layouts/_partials/docs/toc-show.html @@ -1,5 +1,4 @@ {{- return and (not (eq .Params.bookToC false)) (not (eq .Site.Params.BookToC false)) - (not (eq .TableOfContents "")) -}} diff --git a/layouts/_shortcodes/columns.html b/layouts/_shortcodes/columns.html index da2433c..a122062 100644 --- a/layouts/_shortcodes/columns.html +++ b/layouts/_shortcodes/columns.html @@ -1,6 +1,6 @@ {{- $ratio := (split (.Get "ratio") ":") -}} {{- if strings.Contains .InnerDeindent "<--->" -}} -{{- warnf "Columns shortcode separator '<--->' is deprecated, use markdown list instead." -}} +{{- warnf "{{}} shortcode separator '<--->' is deprecated, use markdown list instead." -}} {{- $attributes := partial "docs/text/mapper" (dict "attributes" (cond .IsNamedParams .Params dict) "merge" (dict diff --git a/layouts/_shortcodes/hint.html b/layouts/_shortcodes/hint.html index 8cec90b..f481e5b 100644 --- a/layouts/_shortcodes/hint.html +++ b/layouts/_shortcodes/hint.html @@ -1,4 +1,4 @@ -{{- warnf "Hint shortcode is deprecated, use markdown alerts format: '> [!NOTE] ...'" -}} +{{- warnf "{{}} shortcode is deprecated, use markdown alerts format: '> [!NOTE] ...'" -}} {{- $attributes := partial "docs/text/mapper" (dict "attributes" (cond .IsNamedParams .Params dict) "merge" (dict diff --git a/layouts/_shortcodes/section.html b/layouts/_shortcodes/section.html index cc0959e..029000a 100644 --- a/layouts/_shortcodes/section.html +++ b/layouts/_shortcodes/section.html @@ -1,4 +1,4 @@ -{{- warnf "Section shortcode is deprecated and will be removed" -}} +{{- warnf "{{
}} shortcode is deprecated and will be removed" -}}
{{ range .Page.Pages }}
diff --git a/layouts/all.txt b/layouts/all.txt new file mode 100644 index 0000000..015075c --- /dev/null +++ b/layouts/all.txt @@ -0,0 +1,7 @@ +{{ .Site.Title }} +{{ $section := partialCached "docs/menu-section" .Site -}} +{{- range (partialCached "docs/menu-section-pages" $section) }} +- {{ partial "docs/title" . }}: {{ default .Permalink .Params.BookHref }} +{{- end }} + +{{ .RawContent }} diff --git a/layouts/baseof.html b/layouts/baseof.html index d31cb74..d790b4d 100644 --- a/layouts/baseof.html +++ b/layouts/baseof.html @@ -64,7 +64,6 @@ {{ end }} {{ define "clipboard" }} - {{ with resources.Get "clipboard.js" | resources.Minify }} {{ end }} diff --git a/layouts/book.html b/layouts/book.html new file mode 100644 index 0000000..cdca061 --- /dev/null +++ b/layouts/book.html @@ -0,0 +1,30 @@ +{{ define "menu-container" }} + +{{ end }} + +{{ define "toc" }} + {{ partial "docs/brand" . }} + +{{ end }} + +{{ define "footer" }} + +{{ end }} + +{{ define "main" }} +
+ {{- $section := partialCached "docs/menu-section" .Site -}} + {{- range partialCached "docs/menu-section-pages" $section }} +
{{ .Content }}
+ {{ end }} +
+{{ end }} diff --git a/layouts/book.txt b/layouts/book.txt new file mode 100644 index 0000000..28c01e0 --- /dev/null +++ b/layouts/book.txt @@ -0,0 +1,10 @@ +{{ .Site.Title }} +{{ $section := partialCached "docs/menu-section" .Site -}} +{{- range (partialCached "docs/menu-section-pages" $section) }} +- {{ partial "docs/title" . }}: {{ default .Permalink .Params.BookHref }} +{{- end }} + +{{ $section := partialCached "docs/menu-section" .Site -}} +{{- range (partialCached "docs/menu-section-pages" $section) -}} + {{- .RawContent }} +{{ end -}} diff --git a/layouts/posts/single.html b/layouts/posts/single.html index 232e14e..864978a 100644 --- a/layouts/posts/single.html +++ b/layouts/posts/single.html @@ -16,4 +16,4 @@ {{ define "footer" }} {{ partial "docs/post-prev-next" . }} -{{ end }} \ No newline at end of file +{{ end }}