Posts on Yuanshan Li

Writing technical content in Academic

Fri, 12 Jul 2019 00:00:00 +0000

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 and adding markup: mmark to your page front matter.

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

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 $$\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2$$ renders as $\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2$ .

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-->B;
A-->C;
B-->D;
C-->D;
```

renders as

graph TD;
A-->B;
A-->C;
B-->D;
C-->D;

An example sequence diagram:

```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
```

renders as

sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!

An example Gantt diagram:

```mermaid
gantt
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :after a1 , 20d
section Another
Task in sec :2014-01-12 , 12d
another task : 24d
```

renders as

gantt
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :after a1 , 20d
section Another
Task in sec :2014-01-12 , 12d
another task : 24d

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

First Header	Second Header
Content Cell	Content Cell
Content Cell	Content Cell

Asides

Academic supports a Markdown extension for asides, also referred to as notices or hints. By prefixing a paragraph with A>, it will render as an aside. You can enable this feature by adding markup: mmark to your page front matter, or alternatively using the Alert shortcode.

A> A Markdown aside is useful for displaying notices, hints, or definitions to your readers.

renders as

Display Jupyter Notebooks with Academic

Tue, 05 Feb 2019 00:00:00 +0000

from IPython.core.display import Image
Image('https://www.python.org/static/community_logos/python-logo-master-v3-TM-flattened.png')

print("Welcome to Academic!")

Welcome to Academic!

Install Python and Jupyter

Install Anaconda which includes Python 3 and Jupyter notebook.

Otherwise, for advanced users, install Jupyter notebook with pip3 install jupyter.

Create a new blog post as usual

Run the following commands in your Terminal, substituting <MY_WEBSITE_FOLDER> and my-post with the file path to your Academic website folder and a name for your blog post (without spaces), respectively:

cd <MY_WEBSITE_FOLDER>
hugo new --kind post post/my-post
cd <MY_WEBSITE_FOLDER>/content/post/my-post/

Create or upload a Jupyter notebook

Run the following command to start Jupyter within your new blog post folder. Then create a new Jupyter notebook (New > Python Notebook) or upload a notebook.

jupyter notebook

Convert notebook to Markdown

jupyter nbconvert Untitled.ipynb --to markdown --NbConvertApp.output_files_dir=.
# Copy the contents of Untitled.md and append it to index.md:
cat Untitled.md | tee -a index.md
# Remove the temporary file:
rm Untitled.md

Edit your post metadata

Open index.md in your text editor and edit the title etc. in the front matter according to your preference.

To set a featured image, place an image named featured into your post’s folder.

For other tips, such as using math, see the guide on writing content with Academic.

Academic: the website builder for Hugo

Wed, 20 Apr 2016 00:00:00 +0000

Create a free website with Academic using Markdown, Jupyter, or RStudio. Choose a beautiful color theme and build anything with the Page Builder - over 40 widgets, themes, and language packs included!

Check out the latest demo of what you’ll get in less than 10 minutes, or view the showcase of personal, project, and business sites.

Setup Academic
Get Started
View the documentation
Ask a question
Request a feature or report a bug
Updating? View the Update Guide and Release Notes
Support development of Academic:

Key features:

Page builder - Create anything with widgets and elements
Edit any type of content - Blog posts, publications, talks, slides, projects, and more!
Create content in Markdown, Jupyter, or RStudio
Plugin System - Fully customizable color and font themes
Display Code and Math - Code highlighting and LaTeX math supported
Integrations - Google Analytics, Disqus commenting, Maps, Contact Forms, and more!
Beautiful Site - Simple and refreshing one page design
Industry-Leading SEO - Help get your website found on search engines and social media
Media Galleries - Display your images and videos with captions in a customizable gallery
Mobile Friendly - Look amazing on every screen with a mobile friendly version of your site
Multi-language - 15+ language packs including English, 中文, and Português
Multi-user - Each author gets their own profile page
Privacy Pack - Assists with GDPR
Stand Out - Bring your site to life with animation, parallax backgrounds, and scroll effects
One-Click Deployment - No servers. No databases. Only files.

Color Themes

Academic comes with day (light) and night (dark) mode built-in. Click the sun/moon icon in the top right of the Demo to see it in action!

Choose a stunning color and font theme for your site. Themes are fully customizable and include:

Ecosystem

Academic Admin: An admin tool to import publications from BibTeX or import assets for an offline site
Academic Scripts: Scripts to help migrate content to new versions of Academic

Install

You can choose from one of the following four methods to install:

Then personalize and deploy your new site.

Updating

View the Update Guide.

Feel free to star the project on Github to help keep track of updates.

License

Released under the MIT license.

Posts on Yuanshan Li

Writing technical content in Academic

Examples

Code

Math

Diagrams

Todo lists

Tables

Asides

Did you find this page helpful? Consider sharing it 🙌

Display Jupyter Notebooks with Academic

Install Python and Jupyter

Create a new blog post as usual

Create or upload a Jupyter notebook

Convert notebook to Markdown

Edit your post metadata

Academic: the website builder for Hugo

Color Themes

Ecosystem

Install

Updating

License