This guide shows how to use admonitions and directives in this blog’s markdown to improve content presentation.

Inline Directives :name[label]{attributes}

You can use inline directives to add special formatting or functionality to specific parts of your text. One common use case is to create styled buttons for keyboard shortcuts or UI elements:

:btn[cmd], :btn[shift], :btn[ctrl], :btn[opt], :btn[enter],
:btn[left], :btn[right], :btn[up], :btn[down], :btn[tab],
:btn[space], :btn[delete], :btn[esc], :btn[custom]

Another example is embedding YouTube links directly in your text:

Watch this video on YouTube: :youtube[Click here]{#dQw4w9WgXcQ}.

Block Directives ::name[label]{attributes}

YouTube Embeds

You can also embed YouTube videos as standalone blocks using block directives:

::youtube[Watch this amazing video]{#dQw4w9WgXcQ}

Art Blocks

We also have ::art directives for embedding decorative SVG patterns, which can be used to add visual interest to your posts:

::art{type="wave" color="blue"}

Import code from GitHub

Use a GitHub blob URL in a github-code directive. The code is fetched when the post is rendered and uses the same highlighting, copy button, and optional line numbers as a regular code block. If title is not specified, the filename is used as the title.

::github-code{url="https://github.com/kkensuke/pages/blob/main/next.config.js" title="next.config.js" language="javascript" showLineNumbers=true lines="2-8"}

2const nextConfig = {
3  reactStrictMode: true,
4  swcMinify: true,
5  i18n: {
6    locales: ["en", "ja"],
7    defaultLocale: "en",
8  },

Link card

:::linkcard
https://www.google.com/
:::

Admonitions

Admonitions are specially formatted content blocks that help highlight important information.

Basic Syntax

:::type
Your content here
:::

Available Types

:::note
This is a note admonition.
:::

Custom Titles

:::note{title="Did you know?"}
You can customize the title of any admonition!
:::

Nested Admonitions

You can nest admonitions by using more colons in the opening and closing tags:

Best Practices

1. Use inline directives (:) for elements that are part of your text flow
2. Use block directives (::) for standalone elements like embeds
3. Choose appropriate admonition types based on your content
4. Use clear, descriptive titles for your admonitions
5. Don't overuse admonitions - use them to highlight truly important information