390 lines
9.5 KiB
Markdown
390 lines
9.5 KiB
Markdown
---
|
|
title: Writing technical content in Markdown
|
|
date: 2019-07-12
|
|
math: true
|
|
image:
|
|
placement: 2
|
|
caption: 'Image credit: [**John Moeses Bauan**](https://unsplash.com/photos/OGZtQF8iC0g)'
|
|
---
|
|
|
|
Hugo Blox Builder is designed to give technical content creators a seamless experience. You can focus on the content and Wowchemy handles the rest.
|
|
|
|
**Highlight your code snippets, take notes on math classes, and draw diagrams from textual representation.**
|
|
|
|
On this page, you'll find some examples of the types of technical content that can be rendered with Wowchemy.
|
|
|
|
## Examples
|
|
|
|
### Code
|
|
|
|
Wowchemy supports a Markdown extension for highlighting code syntax. You can customize the styles under the `syntax_highlighter` option in your `config/_default/params.yaml` file.
|
|
|
|
```python
|
|
import pandas as pd
|
|
data = pd.read_csv("data.csv")
|
|
data.head()
|
|
```
|
|
|
|
renders as
|
|
|
|
```python
|
|
import pandas as pd
|
|
data = pd.read_csv("data.csv")
|
|
data.head()
|
|
```
|
|
|
|
### Mindmaps
|
|
|
|
Wowchemy supports a Markdown extension for mindmaps.
|
|
|
|
Simply insert a Markdown `markmap` code block and optionally set the height of the mindmap as shown in the example below.
|
|
|
|
A simple mindmap defined as a Markdown list:
|
|
|
|
<div class="highlight">
|
|
<pre class="chroma">
|
|
<code>
|
|
```markmap {height="200px"}
|
|
- Hugo Modules
|
|
- wowchemy
|
|
- blox-plugins-netlify
|
|
- blox-plugins-netlify-cms
|
|
- blox-plugins-reveal
|
|
```
|
|
</code>
|
|
</pre>
|
|
</div>
|
|
|
|
renders as
|
|
|
|
```markmap {height="200px"}
|
|
- Hugo Modules
|
|
- wowchemy
|
|
- blox-plugins-netlify
|
|
- blox-plugins-netlify-cms
|
|
- blox-plugins-reveal
|
|
```
|
|
|
|
A more advanced mindmap with formatting, code blocks, and math:
|
|
|
|
<div class="highlight">
|
|
<pre class="chroma">
|
|
<code>
|
|
```markmap
|
|
- Mindmaps
|
|
- Links
|
|
- [Wowchemy Docs](https://docs.hugoblox.com/)
|
|
- [Discord Community](https://discord.gg/z8wNYzb)
|
|
- [GitHub](https://github.com/HugoBlox/hugo-blox-builder)
|
|
- Features
|
|
- Markdown formatting
|
|
- **inline** ~~text~~ *styles*
|
|
- multiline
|
|
text
|
|
- `inline code`
|
|
-
|
|
```js
|
|
console.log('hello');
|
|
console.log('code block');
|
|
```
|
|
- Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
|
|
```
|
|
</code>
|
|
</pre>
|
|
</div>
|
|
|
|
renders as
|
|
|
|
```markmap
|
|
- Mindmaps
|
|
- Links
|
|
- [Wowchemy Docs](https://docs.hugoblox.com/)
|
|
- [Discord Community](https://discord.gg/z8wNYzb)
|
|
- [GitHub](https://github.com/HugoBlox/hugo-blox-builder)
|
|
- Features
|
|
- Markdown formatting
|
|
- **inline** ~~text~~ *styles*
|
|
- multiline
|
|
text
|
|
- `inline code`
|
|
-
|
|
```js
|
|
console.log('hello');
|
|
console.log('code block');
|
|
```
|
|
- Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
|
|
```
|
|
|
|
### Charts
|
|
|
|
Wowchemy supports the popular [Plotly](https://plot.ly/) format for interactive charts.
|
|
|
|
Save your Plotly JSON in your page folder, for example `line-chart.json`, and then add the `{{</* chart data="line-chart" */>}}` shortcode where you would like the chart to appear.
|
|
|
|
Demo:
|
|
|
|
{{< chart data="line-chart" >}}
|
|
|
|
You might also find the [Plotly JSON Editor](http://plotly-json-editor.getforge.io/) useful.
|
|
|
|
### Math
|
|
|
|
Wowchemy supports a Markdown extension for $\LaTeX$ math. You can enable this feature by toggling the `math` option in your `config/_default/params.yaml` file.
|
|
|
|
To render _inline_ or _block_ math, wrap your LaTeX math with `{{</* math */>}}$...${{</* /math */>}}` or `{{</* math */>}}$$...$${{</* /math */>}}`, respectively. (We wrap the LaTeX math in the Wowchemy _math_ shortcode to prevent Hugo rendering our math as Markdown. The _math_ shortcode is new in v5.5-dev.)
|
|
|
|
Example **math block**:
|
|
|
|
```latex
|
|
{{</* math */>}}
|
|
$$
|
|
\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}
|
|
$$
|
|
{{</* /math */>}}
|
|
```
|
|
|
|
renders as
|
|
|
|
{{< math >}}
|
|
$$\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}$$
|
|
{{< /math >}}
|
|
|
|
Example **inline math** `{{</* math */>}}$\nabla F(\mathbf{x}_{n})${{</* /math */>}}` renders as {{< math >}}$\nabla F(\mathbf{x}_{n})${{< /math >}}.
|
|
|
|
Example **multi-line math** using the math linebreak (`\\`):
|
|
|
|
```latex
|
|
{{</* math */>}}
|
|
$$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\
|
|
1-p_{0}^{*} & \text{if }k=0.\end{cases}$$
|
|
{{</* /math */>}}
|
|
```
|
|
|
|
renders as
|
|
|
|
{{< math >}}
|
|
|
|
$$
|
|
f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\
|
|
1-p_{0}^{*} & \text{if }k=0.\end{cases}
|
|
$$
|
|
|
|
{{< /math >}}
|
|
|
|
### Diagrams
|
|
|
|
Wowchemy supports a Markdown extension for diagrams. You can enable this feature by toggling the `diagram` option in your `config/_default/params.toml` file or by adding `diagram: true` to your page front matter.
|
|
|
|
An example **flowchart**:
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Hard] -->|Text| B(Round)
|
|
B --> C{Decision}
|
|
C -->|One| D[Result 1]
|
|
C -->|Two| E[Result 2]
|
|
```
|
|
|
|
renders as
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Hard] -->|Text| B(Round)
|
|
B --> C{Decision}
|
|
C -->|One| D[Result 1]
|
|
C -->|Two| E[Result 2]
|
|
```
|
|
|
|
An example **sequence diagram**:
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
Alice->>John: Hello John, how are you?
|
|
loop Healthcheck
|
|
John->>John: Fight against hypochondria
|
|
end
|
|
Note right of John: Rational thoughts!
|
|
John-->>Alice: Great!
|
|
John->>Bob: How about you?
|
|
Bob-->>John: Jolly good!
|
|
```
|
|
|
|
renders as
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
Alice->>John: Hello John, how are you?
|
|
loop Healthcheck
|
|
John->>John: Fight against hypochondria
|
|
end
|
|
Note right of John: Rational thoughts!
|
|
John-->>Alice: Great!
|
|
John->>Bob: How about you?
|
|
Bob-->>John: Jolly good!
|
|
```
|
|
|
|
An example **Gantt diagram**:
|
|
|
|
```mermaid
|
|
gantt
|
|
section Section
|
|
Completed :done, des1, 2014-01-06,2014-01-08
|
|
Active :active, des2, 2014-01-07, 3d
|
|
Parallel 1 : des3, after des1, 1d
|
|
Parallel 2 : des4, after des1, 1d
|
|
Parallel 3 : des5, after des3, 1d
|
|
Parallel 4 : des6, after des4, 1d
|
|
```
|
|
|
|
renders as
|
|
|
|
```mermaid
|
|
gantt
|
|
section Section
|
|
Completed :done, des1, 2014-01-06,2014-01-08
|
|
Active :active, des2, 2014-01-07, 3d
|
|
Parallel 1 : des3, after des1, 1d
|
|
Parallel 2 : des4, after des1, 1d
|
|
Parallel 3 : des5, after des3, 1d
|
|
Parallel 4 : des6, after des4, 1d
|
|
```
|
|
|
|
An example **class diagram**:
|
|
|
|
```mermaid
|
|
classDiagram
|
|
Class01 <|-- AveryLongClass : Cool
|
|
Class03 *-- Class04
|
|
Class05 o-- Class06
|
|
Class07 .. Class08
|
|
Class09 --> C2 : Where am i?
|
|
Class09 --* C3
|
|
Class09 --|> Class07
|
|
Class07 : equals()
|
|
Class07 : Object[] elementData
|
|
Class01 : size()
|
|
Class01 : int chimp
|
|
Class01 : int gorilla
|
|
Class08 <--> C2: Cool label
|
|
```
|
|
|
|
renders as
|
|
|
|
```mermaid
|
|
classDiagram
|
|
Class01 <|-- AveryLongClass : Cool
|
|
Class03 *-- Class04
|
|
Class05 o-- Class06
|
|
Class07 .. Class08
|
|
Class09 --> C2 : Where am i?
|
|
Class09 --* C3
|
|
Class09 --|> Class07
|
|
Class07 : equals()
|
|
Class07 : Object[] elementData
|
|
Class01 : size()
|
|
Class01 : int chimp
|
|
Class01 : int gorilla
|
|
Class08 <--> C2: Cool label
|
|
```
|
|
|
|
An example **state diagram**:
|
|
|
|
```mermaid
|
|
stateDiagram
|
|
[*] --> Still
|
|
Still --> [*]
|
|
Still --> Moving
|
|
Moving --> Still
|
|
Moving --> Crash
|
|
Crash --> [*]
|
|
```
|
|
|
|
renders as
|
|
|
|
```mermaid
|
|
stateDiagram
|
|
[*] --> Still
|
|
Still --> [*]
|
|
Still --> Moving
|
|
Moving --> Still
|
|
Moving --> Crash
|
|
Crash --> [*]
|
|
```
|
|
|
|
### Todo lists
|
|
|
|
You can even write your todo lists in Markdown too:
|
|
|
|
```markdown
|
|
- [x] Write math example
|
|
- [x] Write diagram example
|
|
- [ ] Do something else
|
|
```
|
|
|
|
renders as
|
|
|
|
- [x] Write math example
|
|
- [x] Write diagram example
|
|
- [ ] Do something else
|
|
|
|
### Tables
|
|
|
|
Save your spreadsheet as a CSV file in your page's folder and then render it by adding the _Table_ shortcode to your page:
|
|
|
|
```go
|
|
{{</* table path="results.csv" header="true" caption="Table 1: My results" */>}}
|
|
```
|
|
|
|
renders as
|
|
|
|
{{< table path="results.csv" header="true" caption="Table 1: My results" >}}
|
|
|
|
### Callouts
|
|
|
|
Academic supports a [shortcode for callouts](https://docs.hugoblox.com/content/writing-markdown-latex/#callouts), also referred to as _asides_, _hints_, or _alerts_. By wrapping a paragraph in `{{%/* callout note */%}} ... {{%/* /callout */%}}`, it will render as an aside.
|
|
|
|
```markdown
|
|
{{%/* callout note */%}}
|
|
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
|
|
{{%/* /callout */%}}
|
|
```
|
|
|
|
renders as
|
|
|
|
{{% callout note %}}
|
|
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
|
|
{{% /callout %}}
|
|
|
|
### Spoilers
|
|
|
|
Add a spoiler to a page to reveal text, such as an answer to a question, after a button is clicked.
|
|
|
|
```markdown
|
|
{{</* spoiler text="Click to view the spoiler" */>}}
|
|
You found me!
|
|
{{</* /spoiler */>}}
|
|
```
|
|
|
|
renders as
|
|
|
|
{{< spoiler text="Click to view the spoiler" >}} You found me! {{< /spoiler >}}
|
|
|
|
### Icons
|
|
|
|
Academic enables you to use a wide range of [icons from _Font Awesome_ and _Academicons_](https://docs.hugoblox.com/getting-started/page-builder/#icons) in addition to [emojis](https://docs.hugoblox.com/content/writing-markdown-latex/#emojis).
|
|
|
|
Here are some examples using the `icon` shortcode to render icons:
|
|
|
|
```markdown
|
|
{{</* icon name="terminal" pack="fas" */>}} Terminal
|
|
{{</* icon name="python" pack="fab" */>}} Python
|
|
{{</* icon name="r-project" pack="fab" */>}} R
|
|
```
|
|
|
|
renders as
|
|
|
|
{{< icon name="terminal" pack="fas" >}} Terminal
|
|
{{< icon name="python" pack="fab" >}} Python
|
|
{{< icon name="r-project" pack="fab" >}} R
|
|
|
|
### Did you find this page helpful? Consider sharing it 🙌
|