|
@@ -0,0 +1,310 @@
|
|
|
+---
|
|
|
+title: Writing technical content in Markdown
|
|
|
+date: 2019-07-12
|
|
|
+math: true
|
|
|
+diagram: true
|
|
|
+highlight: true
|
|
|
+image:
|
|
|
+ placement: 2
|
|
|
+ caption: 'Image credit: [**John Moeses Bauan**](https://unsplash.com/photos/OGZtQF8iC0g)'
|
|
|
+---
|
|
|
+
|
|
|
+Wowchemy 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 enable this feature by toggling the `syntax_highlighter` option in your `config/_default/params.toml` 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()
|
|
|
+```
|
|
|
+
|
|
|
+### 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
|
|
|
+ <<interface>> Class01
|
|
|
+ Class09 --> C2 : Where am i?
|
|
|
+ Class09 --* C3
|
|
|
+ Class09 --|> Class07
|
|
|
+ Class07 : equals()
|
|
|
+ Class07 : Object[] elementData
|
|
|
+ Class01 : size()
|
|
|
+ Class01 : int chimp
|
|
|
+ Class01 : int gorilla
|
|
|
+ class Class10 {
|
|
|
+ <<service>>
|
|
|
+ int id
|
|
|
+ size()
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+renders as
|
|
|
+
|
|
|
+```mermaid
|
|
|
+classDiagram
|
|
|
+Class01 <|-- AveryLongClass : Cool
|
|
|
+<<interface>> Class01
|
|
|
+Class09 --> C2 : Where am i?
|
|
|
+Class09 --* C3
|
|
|
+Class09 --|> Class07
|
|
|
+Class07 : equals()
|
|
|
+Class07 : Object[] elementData
|
|
|
+Class01 : size()
|
|
|
+Class01 : int chimp
|
|
|
+Class01 : int gorilla
|
|
|
+class Class10 {
|
|
|
+ <<service>>
|
|
|
+ int id
|
|
|
+ size()
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+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://wowchemy.com/docs/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://sourcethemes.com/academic/docs/page-builder/#icons) in addition to [emojis](https://sourcethemes.com/academic/docs/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 🙌
|