mirror of
https://github.com/thegeeklab/hugo-geekdoc.git
synced 2024-11-21 20:30:39 +00:00
feat: add option to include pages using the include shortcode (#92)
BREAKING CHANGE: The include shortcode will render files as Markdown instead of HTML by default now. While the Markdown renderer should be able to render HTML as well this might still work as before. BREAKING CHANGE: The include shortcode option markdown was replaces by a generic type option that could be used to specify special include types.
This commit is contained in:
GitHub
parent
9129b07d2f
commit
1ace505d27
3
exampleSite/content/_includes/_index.md
Normal file
3
exampleSite/content/_includes/_index.md
Normal file
@ -0,0 +1,3 @@
|
||||
---
|
||||
GeekdocHidden: true
|
||||
---
|
||||
10
exampleSite/content/_includes/include-page.md
Normal file
10
exampleSite/content/_includes/include-page.md
Normal file
@ -0,0 +1,10 @@
|
||||
_**Example page include**_
|
||||
|
||||
{{< hint info >}}
|
||||
**Example Shortcode**\
|
||||
Shortcode used in an include page.
|
||||
{{< /hint >}}
|
||||
|
||||
| Head 1 | Head 2 | Head 3 |
|
||||
| ------ | ------ | ------ |
|
||||
| 1 | 2 | 3 |
|
||||
@ -1,6 +1,11 @@
|
||||
Include shortcode can include files of different types. By specifying a language, the included file will have syntax highlighting.
|
||||
---
|
||||
# Empty front matter as shortcodes could not be includes
|
||||
# as first line of a file.
|
||||
---
|
||||
|
||||
## Shortcode
|
||||
{{< toc >}}
|
||||
|
||||
Include shortcode can include files of different types. By specifying a language, the included file will have syntax highlighting.
|
||||
|
||||
```tpl
|
||||
{{</* include file="relative/path/from/hugo/root" language="go" markdown=[false|true] */>}}
|
||||
@ -8,31 +13,18 @@ Include shortcode can include files of different types. By specifying a language
|
||||
|
||||
Attributes:
|
||||
|
||||
| Name | Usage | default |
|
||||
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
||||
| file | path to the included file relative to the hugo root | empty value |
|
||||
| language\* | language for [syntax highlighting](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) | empty value |
|
||||
| markdown | included file is markdown | false |
|
||||
| options | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) | linenos=table |
|
||||
| Name | Usage | default |
|
||||
| -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
||||
| file | path to the included file relative to the hugo root | undefined |
|
||||
| language | language for [syntax highlighting](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) | undefined |
|
||||
| type | special include type (`html,page`) | undefined |
|
||||
| options | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) | linenos=table |
|
||||
|
||||
\* if not set, the content will be rendered as plain HTML
|
||||
## Examples
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
### Include \*.yml file with options
|
||||
### Markdown file (default)
|
||||
|
||||
```tpl
|
||||
{{</* include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" */>}}
|
||||
```
|
||||
|
||||
<!-- spellchecker-disable -->
|
||||
|
||||
{{< include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100">}}
|
||||
|
||||
<!-- spellchecker-enable -->
|
||||
|
||||
### Include \*.md file
|
||||
|
||||
Included markdown files will be rendered using the `RenderString` [function](https://gohugo.io/functions/renderstring/).
|
||||
If no other options are specified, files will be rendered as Markdown using the `RenderString` [function](https://gohugo.io/functions/renderstring/).
|
||||
|
||||
{{< hint warning >}}
|
||||
**Location of markdown files**\
|
||||
@ -40,21 +32,56 @@ If you include markdown files that should not get a menu entry, place them outsi
|
||||
{{< /hint >}}
|
||||
|
||||
```tpl
|
||||
{{</* include file="static/includes/table.md.part" markdown="true" */>}}
|
||||
{{</* include file="/static/_includes/example.md.part" */>}}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
<!-- spellchecker-disable -->
|
||||
|
||||
{{< include file="static/includes/table.md.part" markdown="true" >}}
|
||||
|
||||
{{< include file="/static/_includes/example.md.part" >}}
|
||||
<!-- spellchecker-enable -->
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Include \*.html file
|
||||
### Language files
|
||||
|
||||
This method can be used to include source code files and keep them automatically up to date.
|
||||
|
||||
```tpl
|
||||
{{</* include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" */>}}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
<!-- spellchecker-disable -->
|
||||
{{< include file="config.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100">}}
|
||||
<!-- spellchecker-enable -->
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Special include types
|
||||
|
||||
#### HTML
|
||||
|
||||
HTML content will be filtered by the `safeHTML` filter and added to the rendered page output.
|
||||
|
||||
```tpl
|
||||
{{</* include file="static/includes/example.html.part" */>}}
|
||||
{{</* include file="/static/_includes/example.html.part" */>}}
|
||||
```
|
||||
|
||||
{{< include file="static/includes/example.html.part" >}}
|
||||
{{< include file="/static/_includes/example.html.part" type="html" >}}
|
||||
|
||||
#### Pages
|
||||
|
||||
In some situations, it can be helpful to include Markdown files that also contain shortcodes. While the [default method](#markdown-file-default) works fine to render plain Markdown, shortcodes are not parsed. The only way to get this to work is to use Hugo pages. There are several ways to structure these include pages, so whatever you do, keep in mind that Hugo needs to be able to render and serve these files as regular pages! How it works:
|
||||
|
||||
1. First you need to create a directory **within** your content directory. For this example site `_includes` is used.
|
||||
2. To prevent the theme from embedding the page in the navigation, create a file `_includes/_index.md` and add `GeekdocHidden: true` to the front matter.
|
||||
3. Place your Markdown files within the `_includes` folder e.g. `/_includes/include-page.md`. Make sure to name it `*.md`.
|
||||
4. Include the page using `{{</* include file="/_includes/include-page.md" */>}}`.
|
||||
|
||||
Resulting structure should look like this:
|
||||
|
||||
```Shell
|
||||
_includes/
|
||||
├── include-page.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
{{< include file="/_includes/include-page.md" type="page" >}}
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
<h1>This is heading 1</h1>
|
||||
<h2>This is heading 2</h2>
|
||||
<h3>This is heading 3</h3>
|
||||
<p>
|
||||
<i><b>Example HTML include</b></i>
|
||||
</p>
|
||||
|
||||
<h4>This is heading 4</h4>
|
||||
<h5>This is heading 5</h5>
|
||||
<h6>This is heading 6</h6>
|
||||
7
exampleSite/static/_includes/example.md.part
Normal file
7
exampleSite/static/_includes/example.md.part
Normal file
@ -0,0 +1,7 @@
|
||||
_**Example Mardown include**_
|
||||
|
||||
File including a simple Markdown table.
|
||||
|
||||
| Head 1 | Head 2 | Head 3 |
|
||||
| ------ | ------ | ------ |
|
||||
| 1 | 2 | 3 |
|
||||
@ -1,5 +0,0 @@
|
||||
#### Test Table
|
||||
|
||||
| Head 1 | Head 2 | Head 3 |
|
||||
|---|---|---|
|
||||
| 1 | 2 | 3 |
|
||||
@ -1,10 +1,17 @@
|
||||
{{ $file := .Get "file" }}
|
||||
{{ $page := .Site.GetPage $file }}
|
||||
{{ $type := .Get "type" }}
|
||||
{{ $language := .Get "language" }}
|
||||
{{ $options :=.Get "options" }}
|
||||
|
||||
<div class="gdoc-include">
|
||||
{{- if eq (.Get "markdown") "true" -}}
|
||||
{{- $file | readFile | $.Page.RenderString -}}
|
||||
{{- else if (.Get "language") -}}
|
||||
{{- highlight ($file | readFile) (.Get "language") (default "linenos=table" (.Get "options")) -}}
|
||||
{{- if (.Get "language") -}}
|
||||
{{- highlight ($file | readFile) $language (default "linenos=table" $options) -}}
|
||||
{{- else if eq $type "html" -}}
|
||||
{{- $file | readFile | safeHTML -}}
|
||||
{{- else if eq $type "page" -}}
|
||||
{{- with $page }}{{ .Content }}{{ end -}}
|
||||
{{- else -}}
|
||||
{{ $file | readFile | safeHTML }}
|
||||
{{- $file | readFile | $.Page.RenderString -}}
|
||||
{{- end -}}
|
||||
</div>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user