如何给本站添加文章

steps

1. Clone this repo from GitHub
2. Create a post under /_posts/. See “A Post” section below for details
3. Commit then push.

expected behavior:

• The push to GitHub kicks off a sequence GitHub Actions
• The new post is live at the site
• A small commit like this takes about one minute from push to live.

A Post

file name

File names of posts should be <YEAR>-<MONTH>-<DAY>-<title>.md where title should a sequence of hyphen separated ASCII words. File names will be used in links, non-ASCII character would be unreadable after URL encoding. Blank spaces are replaced with hyphen automatically by Jekyll

good:
2022-10-17-howto-write-a-post.md
bad:
2022-10-17-howto write a post.md
2022-10-17-如何添加文章.md

front matter

The front matter must be the first thing in the file.

example:

---
title: 如何给本站添加文章
categories: [HowTo]
tags: [chore]
---

For anything else, refer to Jekyll doc.

fields

• title: blog title. Use any character you want
• date: ADD THIS FIELD IF YOUR MUST. this field override dates in file name
• categories: CamelCase category name, [CategoryOne]. Using multiple category names means sub-category e.g. [Animal, Mammal]
• tags: list of kebab-case tag names, [tag-one, tag-two]

image assets

When possible, use mermaid-js to generate graphs.

Images should be in /assets/blog-images. Links in markdown should have prefix /assets/blog-images.

FIXME

The set up above would cause markdown editor to be unable to locate and render images. This behavior is not desirable. I am working on a better solution.

other guidelines

1. Markdown titles and subtitles are used to generate permalink, use concise ACSII titles if you don’t want your link ends up to be gibberish like example.com/posts/%E5%A6%82%E4%BD%95%E7%BB%99%E6%9C%AC%E7%AB%99%E6%B7%BB%E5%8A%A0%E6%96%87%E7%AB%A0
2. YAML syntax requires a space after colon, see this commit
3. Do not use unidecode characters in image url, see this commit
4. Do not hard code links to blog posts, use {<percent sign> post_url 2022-10-15-howto-write-a-post <percent sign>}. This whole thing will get replaced with correct link at blog build time.
5. coming soon…