docs: add tutorial and example for new features
This commit is contained in:
parent
6fa1777eb0
commit
8440d42984
2 changed files with 113 additions and 77 deletions
|
@ -8,14 +8,12 @@ math: true
|
|||
mermaid: true
|
||||
image:
|
||||
path: /commons/devices-mockup.png
|
||||
width: 800
|
||||
height: 500
|
||||
lqip: data:image/webp;base64,UklGRpoAAABXRUJQVlA4WAoAAAAQAAAADwAABwAAQUxQSDIAAAARL0AmbZurmr57yyIiqE8oiG0bejIYEQTgqiDA9vqnsUSI6H+oAERp2HZ65qP/VIAWAFZQOCBCAAAA8AEAnQEqEAAIAAVAfCWkAALp8sF8rgRgAP7o9FDvMCkMde9PK7euH5M1m6VWoDXf2FkP3BqV0ZYbO6NA/VFIAAAA
|
||||
alt: Responsive rendering of Chirpy theme on multiple devices.
|
||||
---
|
||||
|
||||
This post is to show Markdown syntax rendering on [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork), you can also use it as an example of writing. Now, let's start looking at text and typography.
|
||||
|
||||
|
||||
## Titles
|
||||
---
|
||||
# H1 - heading
|
||||
|
@ -26,7 +24,6 @@ This post is to show Markdown syntax rendering on [**Chirpy**](https://github.co
|
|||
|
||||
<h4>H4 - heading</h4>
|
||||
---
|
||||
<br>
|
||||
|
||||
## Paragraph
|
||||
|
||||
|
@ -95,56 +92,6 @@ Moon
|
|||
|
||||
Click the hook will locate the footnote[^footnote], and here is another footnote[^fn-nth-2].
|
||||
|
||||
## Images
|
||||
|
||||
- Default (with caption)
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" }
|
||||
_Full screen width and center alignment_
|
||||
|
||||
<br>
|
||||
|
||||
- Shadow
|
||||
|
||||
![Window shadow](/posts/20190808/window.png){: .shadow width="1548" height="864" .w-75 }
|
||||
_shadow effect (visible in light mode)_
|
||||
|
||||
<br>
|
||||
|
||||
- Left aligned
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" .w-75 .normal}
|
||||
|
||||
- Float to left
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .left}
|
||||
Praesent maximus aliquam sapien. Sed vel neque in dolor pulvinar auctor. Maecenas pharetra, sem sit amet interdum posuere, tellus lacus eleifend magna, ac lobortis felis ipsum id sapien. Proin ornare rutrum metus, ac convallis diam volutpat sit amet. Phasellus volutpat, elit sit amet tincidunt mollis, felis mi scelerisque mauris, ut facilisis leo magna accumsan sapien. In rutrum vehicula nisl eget tempor. Nullam maximus ullamcorper libero non maximus. Integer ultricies velit id convallis varius. Praesent eu nisl eu urna finibus ultrices id nec ex. Mauris ac mattis quam. Fusce aliquam est nec sapien bibendum, vitae malesuada ligula condimentum. Phasellus a tortor aliquam, tristique felis sit amet, elementum enim. Integer vestibulum vitae nulla nec pretium.
|
||||
|
||||
- Float to right
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .right}
|
||||
Praesent maximus aliquam sapien. Sed vel neque in dolor pulvinar auctor. Maecenas pharetra, sem sit amet interdum posuere, tellus lacus eleifend magna, ac lobortis felis ipsum id sapien. Proin ornare rutrum metus, ac convallis diam volutpat sit amet. Phasellus volutpat, elit sit amet tincidunt mollis, felis mi scelerisque mauris, ut facilisis leo magna accumsan sapien. In rutrum vehicula nisl eget tempor. Nullam maximus ullamcorper libero non maximus. Integer ultricies velit id convallis varius. Praesent eu nisl eu urna finibus ultrices id nec ex. Mauris ac mattis quam. Fusce aliquam est nec sapien bibendum, vitae malesuada ligula condimentum. Phasellus a tortor aliquam, tristique felis sit amet, elementum enim. Integer vestibulum vitae nulla nec pretium.
|
||||
|
||||
## Mermaid SVG
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title Adding GANTT diagram functionality to mermaid
|
||||
apple :a, 2017-07-20, 1w
|
||||
banana :crit, b, 2017-07-23, 1d
|
||||
cherry :active, c, after b a, 1d
|
||||
```
|
||||
|
||||
## Mathematics
|
||||
|
||||
The mathematics powered by [**MathJax**](https://www.mathjax.org/):
|
||||
|
||||
$$ \sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6} $$
|
||||
|
||||
When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are
|
||||
|
||||
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
|
||||
|
||||
## Inline code
|
||||
|
||||
This is an example of `Inline Code`.
|
||||
|
@ -153,7 +100,7 @@ This is an example of `Inline Code`.
|
|||
|
||||
Here is the `/path/to/the/file.extend`{: .filepath}.
|
||||
|
||||
## Code block
|
||||
## Code blocks
|
||||
|
||||
### Common
|
||||
|
||||
|
@ -161,22 +108,12 @@ Here is the `/path/to/the/file.extend`{: .filepath}.
|
|||
This is a common code snippet, without syntax highlight and line number.
|
||||
```
|
||||
|
||||
### Specific Languages
|
||||
|
||||
#### Console
|
||||
|
||||
```console
|
||||
$ env |grep SHELL
|
||||
SHELL=/usr/local/bin/bash
|
||||
PYENV_SHELL=bash
|
||||
```
|
||||
|
||||
#### Shell
|
||||
### Specific Language
|
||||
|
||||
```bash
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "The command was not successful.";
|
||||
#do the needful / exit
|
||||
echo "The command was not successful.";
|
||||
#do the needful / exit
|
||||
fi;
|
||||
```
|
||||
|
||||
|
@ -189,6 +126,58 @@ fi;
|
|||
```
|
||||
{: file='_sass/jekyll-theme-chirpy.scss'}
|
||||
|
||||
## Mathematics
|
||||
|
||||
The mathematics powered by [**MathJax**](https://www.mathjax.org/):
|
||||
|
||||
$$ \sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6} $$
|
||||
|
||||
When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are
|
||||
|
||||
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
|
||||
|
||||
## Mermaid SVG
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title Adding GANTT diagram functionality to mermaid
|
||||
apple :a, 2017-07-20, 1w
|
||||
banana :crit, b, 2017-07-23, 1d
|
||||
cherry :active, c, after b a, 1d
|
||||
```
|
||||
|
||||
## Images
|
||||
|
||||
### Default (with caption)
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" }
|
||||
_Full screen width and center alignment_
|
||||
|
||||
### Left aligned
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" .w-75 .normal}
|
||||
|
||||
### Float to left
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .left}
|
||||
Praesent maximus aliquam sapien. Sed vel neque in dolor pulvinar auctor. Maecenas pharetra, sem sit amet interdum posuere, tellus lacus eleifend magna, ac lobortis felis ipsum id sapien. Proin ornare rutrum metus, ac convallis diam volutpat sit amet. Phasellus volutpat, elit sit amet tincidunt mollis, felis mi scelerisque mauris, ut facilisis leo magna accumsan sapien. In rutrum vehicula nisl eget tempor. Nullam maximus ullamcorper libero non maximus. Integer ultricies velit id convallis varius. Praesent eu nisl eu urna finibus ultrices id nec ex. Mauris ac mattis quam. Fusce aliquam est nec sapien bibendum, vitae malesuada ligula condimentum.
|
||||
|
||||
### Float to right
|
||||
|
||||
![Desktop View](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .right}
|
||||
Praesent maximus aliquam sapien. Sed vel neque in dolor pulvinar auctor. Maecenas pharetra, sem sit amet interdum posuere, tellus lacus eleifend magna, ac lobortis felis ipsum id sapien. Proin ornare rutrum metus, ac convallis diam volutpat sit amet. Phasellus volutpat, elit sit amet tincidunt mollis, felis mi scelerisque mauris, ut facilisis leo magna accumsan sapien. In rutrum vehicula nisl eget tempor. Nullam maximus ullamcorper libero non maximus. Integer ultricies velit id convallis varius. Praesent eu nisl eu urna finibus ultrices id nec ex. Mauris ac mattis quam. Fusce aliquam est nec sapien bibendum, vitae malesuada ligula condimentum.
|
||||
|
||||
### Dark/Light mode & Shadow
|
||||
|
||||
The image below will toggle dark/light mode based on theme preference, notice it has shadows.
|
||||
|
||||
![light mode only](/posts/20190808/devtools-light.png){: .light .w-75 .shadow .rounded-10 w='1212' h='668' }
|
||||
![dark mode only](/posts/20190808/devtools-dark.png){: .dark .w-75 .shadow .rounded-10 w='1212' h='668' }
|
||||
|
||||
## Video
|
||||
|
||||
{% include embed/youtube.html id='Balreaj8Yqs' %}
|
||||
|
||||
## Reverse Footnote
|
||||
|
||||
[^footnote]: The footnote source
|
||||
|
|
|
@ -7,7 +7,7 @@ tags: [writing]
|
|||
render_with_liquid: false
|
||||
---
|
||||
|
||||
This post will guide you how to write a post on _Chirpy_ theme. Even if you have previous experience with Jekyll, this article is worth reading, because many features require specific variables to be set.
|
||||
This tutorial will guide you how to write a post in the _Chirpy_ template, and it's worth reading even if you've used Jekyll before, as many features require specific variables to be set.
|
||||
|
||||
## Naming and Path
|
||||
|
||||
|
@ -177,9 +177,18 @@ By default, the image is centered, but you can specify the position by using one
|
|||
```
|
||||
{: .nolineno}
|
||||
|
||||
### Dark/Light mode
|
||||
|
||||
You can make images follow theme preferences in dark/light mode. This requires you to prepare two images, one for dark mode and one for light mode, and then assign them a specific class (`dark` or `light`):
|
||||
|
||||
```markdown
|
||||
![Light mode only](/path/to/light-mode.png){: .light }
|
||||
![Dark mode only](/path/to/dark-mode.png){: .dark }
|
||||
```
|
||||
|
||||
### Shadow
|
||||
|
||||
The screenshots of the program window can be considered to show the shadow effect, and the shadow will be visible in the `light` mode:
|
||||
The screenshots of the program window can be considered to show the shadow effect:
|
||||
|
||||
```markdown
|
||||
![Desktop View](/assets/img/sample/mockup.png){: .shadow }
|
||||
|
@ -209,7 +218,7 @@ The parsing result will automatically add the CDN prefix `https://cdn.com` befor
|
|||
```html
|
||||
<img src="https://cdn.com/path/to/flower.png" alt="The flower">
|
||||
```
|
||||
{: .nolineno}
|
||||
{: .nolineno }
|
||||
|
||||
### Image Path
|
||||
|
||||
|
@ -220,7 +229,6 @@ When a post contains many images, it will be a time-consuming task to repeatedly
|
|||
img_path: /img/path/
|
||||
---
|
||||
```
|
||||
{: .nolineno }
|
||||
|
||||
And then, the image source of Markdown can write the file name directly:
|
||||
|
||||
|
@ -238,28 +246,49 @@ The output will be:
|
|||
|
||||
### Preview Image
|
||||
|
||||
If you want to add an image to the top of the post contents, specify the attribute `path`, `width`, `height`, and `alt` for the image:
|
||||
If you want to add an image at the top of the article, please provide an image with a resolution of `1200 x 630`. Please note that if the image aspect ratio does not meet `1.91 : 1`, the image will be scaled and cropped.
|
||||
|
||||
Knowing these prerequisites, you can start setting the image's attribute:
|
||||
|
||||
```yaml
|
||||
---
|
||||
image:
|
||||
path: /path/to/image
|
||||
width: 1000 # in pixels
|
||||
height: 400 # in pixels
|
||||
alt: image alternative text
|
||||
---
|
||||
```
|
||||
|
||||
Except for `alt`, all other options are necessary, especially the `width` and `height`, which are related to user experience and web page loading performance. The above section "[Size](#size)" also mentions this.
|
||||
|
||||
Starting from _Chirpy v5.0.0_, the attributes `height` and `width` can be abbreviated: `height` → `h`, `width` → `w`. In addition, the [`img_path`](#image-path) can also be passed to the preview image, that is, when it has been set, the attribute `path` only needs the image file name.
|
||||
|
||||
For simple use, you can also just use `image` to define the path.
|
||||
|
||||
```yml
|
||||
---
|
||||
image: /path/to/image
|
||||
---
|
||||
```
|
||||
|
||||
### LQIP
|
||||
|
||||
For preview images:
|
||||
|
||||
```yaml
|
||||
---
|
||||
image:
|
||||
lqip: /path/to/lqip-file # or base64 URI
|
||||
---
|
||||
```
|
||||
|
||||
> You can observe LQIP in the preview image of post [_Text and Typography_](/posts/text-and-typography/).
|
||||
|
||||
|
||||
For normal images:
|
||||
|
||||
```markdown
|
||||
![Image description](/path/to/image){: lqip="/path/to/lqip-file" }
|
||||
```
|
||||
{: .nolineno }
|
||||
|
||||
## Pinned Posts
|
||||
|
||||
You can pin one or more posts to the top of the home page, and the fixed posts are sorted in reverse order according to their release date. Enable by:
|
||||
|
@ -357,6 +386,24 @@ If you want to display the **Liquid** snippet, surround the liquid code with `{%
|
|||
|
||||
Or adding `render_with_liquid: false` (Requires Jekyll 4.0 or higher) to the post's YAML block.
|
||||
|
||||
## Videos
|
||||
|
||||
You can embed a video with the following syntax:
|
||||
|
||||
```liquid
|
||||
{% include embed/{Platform}.html id='{ID}' %}
|
||||
```
|
||||
Where `Platform` is the lowercase of the platform name, and `ID` is the video ID.
|
||||
|
||||
The following table shows how to get the two parameters we need in a given video URL, and you can also know the currently supported video platforms.
|
||||
|
||||
| Video URL | Platform | ID |
|
||||
|----------------------------------------------------------------------------------------------------|-----------|:--------------|
|
||||
| [https://www.**youtube**.com/watch?v=**H-B46URT4mg**](https://www.youtube.com/watch?v=H-B46URT4mg) | `youtube` | `H-B46URT4mg` |
|
||||
| [https://www.**twitch**.tv/videos/**1634779211**](https://www.twitch.tv/videos/1634779211) | `twitch` | `1634779211` |
|
||||
|
||||
|
||||
|
||||
## Learn More
|
||||
|
||||
For more knowledge about Jekyll posts, visit the [Jekyll Docs: Posts](https://jekyllrb.com/docs/posts/).
|
||||
|
|
Loading…
Reference in a new issue