diff --git a/.dictionary b/.dictionary index 42dac78..7a221d8 100644 --- a/.dictionary +++ b/.dictionary @@ -12,3 +12,4 @@ pre-build submodule GPL IcoMoon +YAML diff --git a/.tarignore b/.tarignore index 2c79ca3..575d4a3 100644 --- a/.tarignore +++ b/.tarignore @@ -1,9 +1,12 @@ +.envrc .tarignore .dictionary* .git* .drone* .lighthouse* .markdownlint* +.jsbeautify* +.prettier* example* gulp* package* diff --git a/exampleSite/content/usage/code-blocks.md b/exampleSite/content/usage/code-blocks.md index 7f9dca3..bf1d12c 100644 --- a/exampleSite/content/usage/code-blocks.md +++ b/exampleSite/content/usage/code-blocks.md @@ -1,5 +1,11 @@ There are multiple ways to add code blocks. Most of them works out of the box only the Hugo shortcode `` need some configuration to work properly. + + +{{< toc >}} + + + ## Inline code To display an inline shortcode use single quotes: diff --git a/exampleSite/content/usage/color-schemes.md b/exampleSite/content/usage/color-schemes.md index 5c8bd9d..cb7551a 100644 --- a/exampleSite/content/usage/color-schemes.md +++ b/exampleSite/content/usage/color-schemes.md @@ -41,4 +41,4 @@ a:visited { color: #73bfb8 } And that is how the result will looks like. Happy customizing! -[![HC-primary Color Scheme](/media/color_scheme_example.png)](/media/color_scheme_example.png) +[![HC-primary Color Scheme](/media/colorscheme-example.png)](/media/colorscheme-example.png) diff --git a/exampleSite/content/usage/configuration.md b/exampleSite/content/usage/configuration.md index 0d2386d..5f780c8 100644 --- a/exampleSite/content/usage/configuration.md +++ b/exampleSite/content/usage/configuration.md @@ -3,6 +3,12 @@ title: Configuration weight: -10 --- + + +{{< toc >}} + + + ## Site configuration {{< tabs "site-config" >}} diff --git a/exampleSite/content/usage/getting-started.md b/exampleSite/content/usage/getting-started.md index deec6aa..3c7fa91 100644 --- a/exampleSite/content/usage/getting-started.md +++ b/exampleSite/content/usage/getting-started.md @@ -22,7 +22,7 @@ If you want to use the theme from a cloned branch instead of a release tarball y npm install # run gulp pipeline to build required assets -gulp default +npx gulp default ``` ## Using the theme @@ -98,5 +98,5 @@ git clone https://github.com/thegeeklab/hugo-geekdoc.git themes/geekdoc Build required theme assets e.g. CSS files and SVG sprites with `gulp`. ```Shell -gulp default +npx gulp default ``` diff --git a/exampleSite/content/usage/menus.md b/exampleSite/content/usage/menus.md index 201db96..cf8c72a 100644 --- a/exampleSite/content/usage/menus.md +++ b/exampleSite/content/usage/menus.md @@ -1,7 +1,98 @@ ---- -draft: true ---- +The theme supports two different kinds of menus. File-tree menu is the default one and does not require further configuration to work. If you want full control about your menu the bundle menu is a powerful option to accomplish it. + + + +{{< toc >}} + + ## File-tree menu +As the name already suggests, the file tree menu builds a menu from the file system structure of the content folder. By default, areas and subareas are sorted alphabetically by the title of the pages. To manipulate the order the `weight` parameter in a page [front matter](https://gohugo.io/content-management/front-matter/) can be used. To structure your content folder you have to use [page bundles](https://gohugo.io/content-management/organization/#page-bundles), single files are **not** supported. Hugo will render build single files in the content folder just fine but it will not be added to the menu. + +**Example:** + +File system structure: + +```plain +content/ +├── level-1 +│   ├── _index.md +│   ├── level-1-1.md +│   ├── level-1-2.md +│   └── level-1-3 +│   ├── _index.md +│   └── level-1-3-1.md +└── level-2 + ├── _index.md + ├── level-2-1.md + └── level-2-2.md +``` + +Generated navigation: + +[![Example file-tree menu](/media/file-tree.png)](/media/file-tree.png) + ## Bundle menu + +This type of navigation needs to be enabled first by setting `geekdocMenuBundle` to `true` in your [site configuration](/usage/configuration/#site-configuration). After you have activated the bundle menu, you start with an empty navigation. This is intentional because bundle menus have to be defined manually in a data file. While this increases the effort it also offers maximum flexibility in the design. The data file needs to be written in YAML and placed at `data/menu/main.yml`. + +**Example:** + +```YAML +--- +main: + - name: Level 1 + ref: "/level-1" + icon: "notification" + sub: + - name: Level 1.1 + ref: "/level-1/level-1-1" + - name: Level 1.2 + ref: "/level-1/level-1-2" + - name: Level 1.3 + ref: "/level-1/level-1-3" + sub: + - name: Level 1.3.1 + ref: "/level-1/level-1-3/level-1-3-1" + - name: Level 2 + ref: "/level-2" + sub: + - name: Level 2.1 + ref: "/level-2/level-2-1" + - name: Level 2.2 + ref: "/level-2/level-2-2" +``` + +As an advantage you can add icons to your menu entries e.g. `icon: "notification"`. + +[![Example bundle menu](/media/bundle-menu.png)](/media/bundle-menu.png) + +### More menu + +{{< hint info >}} +**Tip**\ +The more menu is special type of the bundle menu and can be combined with the default file-tree menu. +{{< /hint >}} + +As this is a special type of the bundle menu it is basically working in the same way. To enable it just add a data file to `data/menu/more.yml`. The more menu will also work with the file-tree menu and therefor **don't need to be enabled** by the `geekdocMenuBundle` parameter. + +**Example:** + +```YAML +--- +more: + - name: News + ref: "/#" + icon: "notification" + - name: Releases + ref: "https://github.com/thegeeklab/hugo-geekdoc/releases" + external: true + icon: "download" + - name: "View Source" + ref: "https://github.com/thegeeklab/hugo-geekdoc" + external: true + icon: "github" +``` + +[![Example bundle menu](/media/more-menu.png)](/media/more-menu.png) diff --git a/exampleSite/static/media/bundle-menu.png b/exampleSite/static/media/bundle-menu.png new file mode 100644 index 0000000..180d739 Binary files /dev/null and b/exampleSite/static/media/bundle-menu.png differ diff --git a/exampleSite/static/media/color_scheme_example.png b/exampleSite/static/media/colorscheme-example.png similarity index 100% rename from exampleSite/static/media/color_scheme_example.png rename to exampleSite/static/media/colorscheme-example.png diff --git a/exampleSite/static/media/file-tree.png b/exampleSite/static/media/file-tree.png new file mode 100644 index 0000000..ae170db Binary files /dev/null and b/exampleSite/static/media/file-tree.png differ diff --git a/exampleSite/static/media/more-menu.png b/exampleSite/static/media/more-menu.png new file mode 100644 index 0000000..a1746db Binary files /dev/null and b/exampleSite/static/media/more-menu.png differ