ドキュメントの文法(シンタックス)【CCG執筆者向け】

ドキュメントの文法(シンタックス)【CCG執筆者向け】

Clock Icon2023.09.11

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

本ブログは ナレッジサイトである Classmethod Cloud Guidebook(CCG) [1] の執筆者向けに公開しているブログです。 一般的なMarkdown(MkDocs)シンタックスでも参考になる部分があると思うので、ブログにて公開しています。

CCGを構成しているドキュメントの文法(シンタックス)を共有します。 執筆の際のリファレンスとして活用してください。

基本の Markdownシンタックス

CCGは 静的サイトジェネレーターである MkDocs (およびその拡張プラグインである Material for MkDocs )から構成されています。 MkDocsでは Markdown で記載されたドキュメントを表示します。

基本的なMarkdown記法については、 普段のブログ執筆などで慣れていると思うので 丁寧に説明しません。

以降で「人によって差異が出やすいポイント」に絞って紹介します。

見出し

見出しはレベル2以降を使います。
見出しレベル1はドキュメントタイトルです。

# ドキュメントタイトル
## 見出しレベル2

見出しレベル2以降を使って、文章を構成ください。

### 見出しレベル3
#### 見出しレベル4
見た目

sc_2024-09-10_11-31-58_28044

段落、改行

段落を作る場合は、空白行を追加してください。
1改行のみの場合は、表示上は改行されません。

空白行を入れて段落を作成。

1改行のみだと、
表示場は改行されない。
見た目

sc_2024-09-10_15-48-23_21196

リスト

リストの前後には空白行を入れてください。
また、ネストする場合は「半角スペース 4つ」を空けてください。

リストの前後には空白行。ネストはスペース4つ。

- アイテム1
    - アイテム1.1
    - アイテム1.2
- アイテム2
見た目

sc_2024-09-10_15-49-32_17790

画像

![イメージタイトル](イメージパス) の形式で画像を挿入します。 イメージパスはリポジトリ内にある画像の場合、相対パスで記載します。

クラスメソッドメンバーズのロゴ

![classmethod](./image/members-logo.png)
見た目

sc_2024-09-10_15-52-30_7752

リンク

[タイトル](URL) 形式で書きます。 タイトルには出典元を載せましょう。

[クラスメソッド発「やってみた」系技術メディア | DevelopersIO](https://dev.classmethod.jp/)
見た目

sc_2024-09-10_16-14-41_29821

コメントアウト

<!-- および --> で括られた部分はコメントアウトとなります。

コメントアウトした情報も、MkDocsのビルドに含まれることに注意してください。
機微な情報は載せないようにしましょう。

おはよう。
<!-- TODO: こんにちわ。 -->
こんばんわ。
見た目

sc_2024-09-10_16-17-06_5497

MkDocs(Material)独自のシンタックス

コールアウト

admonitions(call-outs) を使えます。 目立たせたい情報がある場合に役立ちます。

!!! note "コールアウトの使い方"
    `!!!` から始まるブロックを書くことで、コールアウトを使えます。
    <br> `note` 以外にも `abstract``info` など、様々なタイプがあります。
見た目

sc_2024-09-10_16-20-31_29454

詳しい使い方は以下ページを参考ください。

https://squidfunk.github.io/mkdocs-material/reference/admonitions/

Mermaid描画

Mermaid による図の描画が可能です。 フローチャートなどを書く際に便利です。

\```mermaid
graph TD
  start([スタート]) --> topic[ネタを収集する]
  topic --> blog[ブログを書く]
  blog --> start
\```
見た目

sc_2024-09-10_16-22-14_4255

詳しい使い方は以下ページを参考ください。 もしくは Mermaid リファレンス を参照ください。

https://squidfunk.github.io/mkdocs-material/reference/diagrams/

アイコン、絵文字

アイコンや絵文字を挿入できます。

:motorcycle: :dash:
見た目

sc_2024-09-10_16-23-51_29900

使える絵文字は以下ページで検索できます。

https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/

そのほか

他にも、Material for MkDocs に特化した記法があります。 使いたい場合は以下リファレンスを参照ください。

https://squidfunk.github.io/mkdocs-material/reference/

おわりに

以上、CCGドキュメントの文法(シンタックス)を共有しました。

ガンガン執筆していきましょう!

参考

https://www.mkdocs.org/

https://squidfunk.github.io/mkdocs-material/

脚注
  1. Classmethod Cloud Guidebook(CCG)は クラスメソッドメンバーズ(請求代行サービス)向けに公開している ナレッジサイトです。詳しくは こちらの紹介ブログ を参照ください。 ↩︎

Share this article

facebook logohatena logotwitter logo

© Classmethod, Inc. All rights reserved.