github/hugo-geekblog
0
0
Fork 0
mirror of https://github.com/thegeeklab/hugo-geekblog.git synced 2024-11-24 22:10:39 +00:00
Code Issues Projects Releases Wiki Activity

docs: normalize shortcode documentation (#276)

Browse Source
This commit is contained in:
Robert Kaussow 2022-07-11 14:27:54 +02:00 committed by GitHub
parent 349d6529f1
commit 42f408b2d4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 35 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
exampleSite/content/posts/advanced/includes.md
View File

@ -20,18 +20,18 @@ Include shortcode can include files of different types. By specifying a language
``` ```
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
Attributes: ## Attributes
| Name | Usage | default | | Name | Description | default |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| file | path to the included file relative to the Hugo root | undefined | | 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 | | 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 (rendered as markdown) | | type | special include type (`html,page`) | undefined (rendered as markdown) |
| options | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) | `linenos=table` | | options | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) | `linenos=table` |
## Examples ## Usage
### Markdown file (default) ## Markdown file (default)
If no other options are specified, files will be rendered as Markdown 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/).
@ -51,7 +51,7 @@ If you include markdown files that should not get a menu entry, place them outsi
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
### Language files ## Language files
This method can be used to include source code files and keep them automatically up to date. This method can be used to include source code files and keep them automatically up to date.
@ -68,9 +68,9 @@ Result:
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
### Special include types ## Special include types
#### HTML ### HTML
HTML content will be filtered by the `safeHTML` filter and added to the rendered page output. HTML content will be filtered by the `safeHTML` filter and added to the rendered page output.
@ -81,7 +81,7 @@ HTML content will be filtered by the `safeHTML` filter and added to the rendered
{{< include file="/static/_includes/example.html.part" type="html" >}} {{< include file="/static/_includes/example.html.part" type="html" >}}
#### Pages ### 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: 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:

28
exampleSite/content/posts/advanced/shortcodes.md
View File

@ -36,9 +36,17 @@ Buttons are styled links that can lead to local page or external link.
The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability. The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability.
### Attributes
| Name | Description | default |
| --------------- | ------------------------------------------------ | ------- |
| size (optional) | size of the first column (small\|regular\|large) | regular |
### Usage
<!-- prettier-ignore --> <!-- prettier-ignore -->
```html ```html
{{</* columns */>}} <!-- begin columns block --> {{</* columns [size="small|regular|large"] */>}} <!-- begin columns block -->
# Left Content # Left Content
Dolor sit, sumo unique argument um no ... Dolor sit, sumo unique argument um no ...
@ -160,19 +168,19 @@ copious quo ad. Stet probates in duo.
Hint shortcode can be used as hint/alerts/notification block. Hint shortcode can be used as hint/alerts/notification block.
Attributes: ### Attributes
| Name | Usage | default | | Name | Description | default |
| ---------------- | --------------------------------------------------------------------------------------- | --------------------- | | ---------------- | -------------------------------------------------------------------------------------- | --------- |
| type | color types to choose from | note | | type | hint type | note |
| icon (optional) | custom icon to use | undefined (type name) | | icon (optional) | custom icon to use,need to be an icon from an [SVG sprite](/posts/features/icon-sets/) | undefined |
| title (optional) | custom icon to use, need to be an icon from an [SVG sprite](/posts/features/icon-sets/) | undefined (type name) | | title (optional) | hint title | undefined |
Syntax: ### Usage
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
```tpl ```tpl
{{</* hint type=[note|tip|important|caution|warning] (icon=gblog_github) (title=GitHub) */>}} {{</* hint type="note|tip|important|caution|warning" [icon="gblog_github" title="GitHub"] */>}}
**Markdown content**\ **Markdown content**\
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
Ornateness bland it ex enc, est yeti am bongo detract re. Ornateness bland it ex enc, est yeti am bongo detract re.
@ -307,7 +315,7 @@ prompts feud gait, quid exercise emeritus bis e. In pro quints consequent.
<!-- prettier-ignore --> <!-- prettier-ignore -->
```tpl ```tpl
{{</* mermaid class="text-center"*/>}} {{</* mermaid class="text-center" */>}}
sequenceDiagram sequenceDiagram
Alice->>Bob: Hello Bob, how are you? Alice->>Bob: Hello Bob, how are you?
alt is sick alt is sick

18
exampleSite/content/posts/post-with-images/index.md
View File

@ -53,16 +53,16 @@ If you need more flexibility for your embedded images, you could use the `img` s
<!--more--> <!--more-->
**Attributes:** ## Attributes
| Name | Usage | default | | Name | Description | default |
| ------------- | -------------------------------------------------------------------------------------------------------------- | ----------------- | | ---- | -------------------------------------------------------------------------------------------------------------- | ----------------- |
| name (string) | Name of the image resource defined in your front matter. | empty | | name | Name of the image resource defined in your front matter. | empty |
| alt (string) | Description for displayed image. | resource `.Title` | | alt | Description for displayed image. | resource `.Title` |
| size (string) | Thumbnail size (tiny\|small\|medium\|large). | empty | | size | Thumbnail size (profile\|tiny\|small\|medium\|large). | empty |
| lazy (bool) | Enable or disable image lazy loading. Can be controlled globally by site parameter `geekblogImageLazyLoading`. | true | | lazy | Enable or disable image lazy loading. Can be controlled globally by site parameter `geekblogImageLazyLoading`. | true |
**Example:** ## Usage
Define your resources in the page front matter, custom parameter `params.credits` is optional. Define your resources in the page front matter, custom parameter `params.credits` is optional.
@ -83,7 +83,7 @@ resources:
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
**Demo:** ## Example
<!-- spellchecker-disable --> <!-- spellchecker-disable -->