Skip to content

Latest commit

 

History

History
107 lines (71 loc) · 3.84 KB

blog.md

File metadata and controls

107 lines (71 loc) · 3.84 KB

Agama blog

Here are some suggestions and hints for writing the Agama blog posts.

Style guide

We do not have any special blog style guide besides few rules mentioned below, just use common sense. If you are unsure about something you can check one of these general developer documentation style guides:

Front matter

The front matter is the YAML metadata block at beginning of the MDX file enclosed in the --- markers.

  • The list of tags is defined in the blog/tags.yml file, feel free to add new tags whenever needed
  • The blog post publish date is taken from the file name, if there are multiple posts in the same day you can use the date front matter to specify the time more precisely
  • If the blog post is a generic announcement on behalf of the whole team (e.g. a new Agama release) then do not specify the blog post author. If it is a specific post by a single author then use the author tag in the front matter.
  • See more details in the documentation

Style

  • Use sentence style capitalization in the heading and titles
  • Add a short heading anchor explicitly, although Docusaurus generates them automatically using a predefined anchor avoids changing it after fixing a typo or rewording

Syntax highlighting

Syntax highlighting in code blocks works with the usual three backticks followed by the language name.

```json
{
  "search": "/dev/vda1",
  "delete": true
}
```

Not all languages are enabled by default, if your code is not highlighted for a specific language then very likely it is not enabled. Check the supported languages in node_modules/prismjs/components/prism-*.js files and enable the language in the docusaurus.config.ts configuration file at the additionalLanguages key.

Images

Place the images into the static/img/blog/XXXX-YY-ZZ directory and reference them using the usual Markdown syntax:

![Detailed image description](../static/img/blog/XXXX-YY-ZZ/image.png)

If the image is too large and you want to display it smaller or you want to display two images side-by-side then use the SmallImageBox custom component for that:

import SmallImageBox from "@site/src/components/SmallImageBox";

<SmallImageBox>
  ![Image1](../static/img/blog/XXXX-YY-ZZ/image1.png)
  ![Image2](../static/img/blog/XXXX-YY-ZZ/image2.png)
</SmallImageBox>

Docusaurus admonitions

Docusaurus support using admonitions, fancy information boxes.

:::warning

Important warning!

:::

Note: The empty lines around the text are important!

Anchors

Docusaurus generates anchors for all headings automatically. But in some cases you might need to reference something else, for example an image or code snippet.

In that case use the React component for placing the anchor

<a id="my-anchor"></a>

and reference it with

<a href="#my-anchor">link</a>

Do not use the usual Markdown link, Docusaurus then reports a false positive warning about missing anchor definition. It seems that it checks only for the Markdown anchors and not for the anchors added by the React components...

Make sure the ID is unique and does not conflict with some automatically generated heading anchor.

Referencing

For referencing another blog post just use the full file name and optional anchor, for example:

In Agama 9 we [fixed locking](2024-06-28-agama-9.mdx#live-iso)