Creating a blogdown site for Katyem

Wow, what a ride! From Yihui’s wonderful package, blogdown, to the ins and outs of GitHub, Netifly, Hugo, and the incredibly complicated Academic theme, we have arrived at this (sorry for the buildup, I know you were probably expecting a bit more). I’m convinced if you find someone that can traverse the blogdown map to arrive at a bonafide r-fortified website, you have found an incredible nerd. A nerd with the formidable tenacity to adhere to the thinnest hope of success.

For the record, I have a long history of building sites using a wide variety of approaches from the early days of html in a simple text editor to the glories of CMS packages like Wordpress, Drupal, and Moodle. I’ve recently spent some (excessive) time building an assessment site using primarily php and javascript, and with all that preparation, I still struggled for days to wrap my head around all that blogdown asked of me. Oh yeah, I also have some R progaming experience under my belt, thus my interest in using blogdown to begin with.

Anyway, hopefully, I’ll write more about the details and even think about a quick tutorial (I think that’s what William James said about his first attempt at a textbook).

Here are a few links to instruction sites that I’ve encountered (I’m not endorsing any of them, at this point):

• Setting up your blog with RStudio and blogdown I: Creating the blog
• 7 Ways You Can Further Customize the Hugo Academic Theme
• blogdown
• Allison Hill , official R Nija and R-Lady, has several posts regarding blogdown and Hugo
• Websites in RStudio -> they incorporate Shiny apps

The rest of this post is what was the sample post that I used to make this particular post. I wanted easy access to the examples and thought - hey, I’ll just leave them here. So, here’s your introduction to the wonders of the Academic Theme Wowcemy Theme for Hugo (EDIT: the Academic theme was renamed/branded Wowcemy in Oct 2020. https://gohugo.io/ is the website framework used by the blogdown package).

Academic is designed to give technical content creators a seamless experience. You can focus on the content and Academic 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 Academic.

Examples

Code

Academic supports a Markdown extension for highlighting code syntax. You can enable this feature by toggling the highlight option in your config/_default/params.toml file.

```python
import pandas as pd
data = pd.read_csv("data.csv")
data.head()
```

renders as

import pandas as pd
data = pd.read_csv("data.csv")
data.head()

Math

Academic supports a Markdown extension for $\LaTeX$ math. You can enable this feature by toggling the math option in your config/_default/params.toml file.

To render inline or block math, wrap your LaTeX math with $...$ or $$...$$, respectively.

Example math block:

$$\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}$$

renders as

$$\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}$$

Example inline math $\nabla F(\mathbf{x}_{n})$ renders as $\nabla F(\mathbf{x}_{n})$.

Example multi-line math using the \\\\ math linebreak:

$$f(k;p_0^*) = \begin{cases} p_0^* & \text{if }k=1, \\\\
1-p_0^* & \text {if }k=0.\end{cases}$$

renders as

$$f(k;p_0^*) = \begin{cases} p_0^* & \text{if }k=1, \\
1-p_0^* & \text {if }k=0.\end{cases}$$

Diagrams

Academic 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

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

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

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

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

stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

Todo lists

You can even write your todo lists in Academic too:

- [x] Write math example
- [x] Write diagram example
- [ ] Do something else

renders as

• Write math example
• Write diagram example
• Do something else

Tables

Represent your data in tables:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

renders as

Asides

Academic supports a shortcode for asides, also referred to as notices, hints, or alerts. By wrapping a paragraph in {{% alert note %}} ... {{% /alert %}}, it will render as an aside.

{{% alert note %}}
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
{{% /alert %}}

renders as

Spoilers

Add a spoiler to a page to reveal text, such as an answer to a question, after a button is clicked.

{{< spoiler text="Click to view the spoiler" >}}
You found me!
{{< /spoiler >}}

renders as

Icons

Academic enables you to use a wide range of icons from Font Awesome and Academicons in addition to emojis.

Here are some examples using the icon shortcode to render icons:

{{< icon name="terminal" pack="fas" >}} Terminal  
{{< icon name="python" pack="fab" >}} Python  
{{< icon name="r-project" pack="fab" >}} R

renders as

Terminal
Python
R

Did you find this page helpful? Consider sharing it 🙌