Pasopedia:執筆ガイド

この執筆ガイドでは、Pasopediaのページの書き方と表記方法のルールを説明します。

PasopediaとGit #

Pasopediaのページとサイト全体のデータはGitHub上でGitというシステムに基づいて管理されており、執筆者はPasopediaのリポジトリにPull Requestを送ることによってページの編集・追加の反映を要請する必要があります。

Hugoについて #

PasopediaではHugoという静的サイトジェネレータを使用しているため、全てのページはMarkdownによって記述されます。

ディレクトリ構造 #

各ページは/content/pages/（ページ名）/_index.mdに、Pasopediaの使い方に関わるPasopedia:名前空間のページは/content/docs/（ページ名）/_index.mdに記述します。

以下にディレクトリ構造の例を示します。

pasokonistan/pasopedia
└─content
  ├─docs
  │ └─執筆ガイド
  │    └─_index.md
  └─pages
    └─パソコニスタン
      └─_index.md

フロントマター #

フロントマターはMarkdownファイルに文書のタイトルや著者名を記述できるHugo独自の記法です。hugo new ~.mdコマンドを実行するとテンプレートに基づいてフロントマターが記述済みのMarkdownファイルが生成されますので、ページのタイトルを記入してください。

以下にフロントマターの例を示します。

---
title: "Pasopedia:執筆ガイド"
date: 1970-01-01T00:00:00+00:00
type: docs
---

Shortcode #

また、HugoのテーマにはHugo Bookを使用しているため、Markdownに加えてShortcodeと呼ばれるテーマ独自の記法を使ったリッチな表現も可能です。

以下に利用可能なショートコードとその例を示します。

Hint
Hintショートコードを使うことで強調したい情報や注意事項をブロック表示できます。

{{< hint info or warning or danger >}}
**日本国憲法　第三章　第十一条**  
国民は、すべての基本的人権の享有を妨げられない。
この憲法が国民に保障する基本的人権は、侵すことのできない永久の権利として、現在及び将来の国民に与へられる。
{{< /hint >}}

実際の表示はこのようになります。

日本国憲法　第三章　第十一条
国民は、すべての基本的人権の享有を妨げられない。この憲法が国民に保障する基本的人権は、侵すことのできない永久の権利として、現在及び将来の国民に与へられる。

Tab
Tabショートコードを使うことで複数の情報を無駄なく表示できます。

{{< tabs "helloWorldExamples" >}}
{{< tab "Go" >}}
/* Go Example */
{{< /tab >}}
{{< tab "Python" >}}
/* Python Example */
{{< /tab >}}
{{< tab "FORTRAN" >}}
/* FORTRAN Example */
{{< /tab >}}
{{< /tabs >}}

実際の表示はこのようになります。

package main

import "fmt"

func main() {
    fmt.Println("Hello world")
}

Python

print("Hello world")

FORTRAN

program helloworld
  print *, "Hello world."
end program helloworld

KaTeX
KaTeXショートコードを使うことで数式の組版ができます。

{{< katex display or class="text-center" >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}

実際の表示はこのようになります。

\[f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi\]

これらの他にもHugo BookはColumnやExpandなどのショートコードを備えていますが、可読性を保つためにも上記の3つ以外のショートコードを使用することは避けてください。

表記ガイド（.pasopediarc） #

見出しのレベル #

Pasopediaではページのタイトルがページ先頭にh1要素として埋め込まれるため、本文中の見出しにはレベル2（## Headline）以下の見出しのみを使ってください。
またレベル4（#### Headline）以下の見出しを使うことは極力避けて、代わりに箇条書き（- item）を使ってください。

改行 #

Markdownでは任意の箇所に半角スペースを2つ挿入することでHTMLの<br>要素を使った行内改行ができますが、箇条書きや引用の直後のような改行しないと表示が崩れてしまう場合を除いて段落内では改行しないでください。
- 段落をあらためる場合は改行キーを2回押して、HTMLの<p>要素単位で区切ってください。

句読点 #

原則として和文中の句読点は、と。を、欧文中の句読点は,と.を使います。もちろん、引用した文に含まれる句読点についてはこの限りではありません。
リーダーは……と3点リーダーを2つ重ねたものを使い、。。。や、、、としないでください。

約物と数字 #

括弧やクエスチョンマーク、コロンなどの約物は和文中であれば全角、欧文中であれば半角とします。（例：× "パソコニスタン" → 〇 「パソコニスタン」）
数字は半角のアラビア数字を使います。
暦はYYYY年MM月DD日hh時mm分ss秒(UTC+hh)というフォーマットに従います。時刻は24時間制で表記し、数字のゼロ埋めは行いません。
- たとえば、日本時間でのUNIXエポックを表すときは1970年1月1日9時0分0秒(UTC+9)と表記します。
- 時刻とタイムゾーンは適宜省略してください。
なお、Markdownの強調表現は約物を含む文字列に対して適切に機能しないことがありますが、その場合は強調表現の直前にゼロ幅スペース（）を挟むことで（やや不誠実ではあるものの）機能させることができます。

外来語 #

プロダクト名や人名など、固有名詞の外来語は原則公式の表記に従います。（例：× ユニックス → 〇 UNIX）
- ただし、すでにカタカナで広く知られているものに関してはそちらを尊重してください。
カタカナ表記の末尾にある長音記号（ー）については、1991年の内閣告示「外来語の表記」に従い、原則として省略しないものとします。（例：× サーバ → 〇 サーバー）
- ただし、長音を省略した形で広く知られているものに関してはそちらを尊重してください。
媒体によっては和文中の英単語の前後に半角スペースを挿入して区切る場合がありますが、Pasopediaではこれを行わないものとします。

その他 #

実在の人物の名前を挙げるときは、存命であるかなどに関わらず必ず敬称を付けてください。敬称は「氏」で統一します。
- ただし「○○博士」「○○卿」など、学位や爵位などが敬称として定着している場合はそちらを尊重してください。
- Pasopedia:名前空間のページでは、敬称は適宜使い分けてください。
SNS上の人物の名前を挙げるときはサービス名:@ユーザーIDというフォーマットのアンカー文字列を使います。
- たとえば、パソコニスタンの管理者であるsksatさんの名前を挙げるときは「pasokey:@sksat氏」あるいは「Twitter:@sksat氏」と表記します。
ページ内リンクは#リンク先というフォーマットに従います。
- たとえば、この章に他の章からリンクするときは「#その他」と表記します。
ページ外リンクのアンカー文字列はリンクの行き先を具体的に示すものにしてください。（例： × [こちら](https://go.dev)のサイトから…… → 〇 [Go言語の公式サイト](https://go.dev)から……）