NOTICE.mdでのMarkdown記法の制限を、拡張ページと統合 #1362

faithandbrave · faithandbrave · commit 1395fe501640 · 2024-11-18T14:55:10.000+09:00
diff --git a/.start_editing.md.swp b/.start_editing.md.swp
diff --git a/NOTICE.md b/NOTICE.md
diff --git a/start_editing.md b/start_editing.md
@@ -93,25 +93,14 @@ Markdownの記述方法をわかりやすく解説してくれているWebサイ
 ただし、cpprefjp特有の拡張構文もあります。
 以下のページにまとめてあるので、そちらを参照して下さい。
 
-- [cpprefjp特有の拡張構文](/start_editing/specialized.md)
+- [cpprefjpでのMarkdown記法の制限と拡張](/start_editing/markdown_cpprefjp.md)
 
-Markdown形式では、HTMLのタグも併用できますが、cpprefjpサイトでは積極的にはHTMLタグを使用しない方針です。できるだけ、Markdown形式でできる範囲内で解決するようにしてください。
+Markdown形式では、HTMLのタグも併用できますが、cpprefjpサイトでは積極的にはHTMLタグを使用しない方針で、許可されたタグのみ使用できます。できるだけ、Markdown形式でできる範囲内で解決するようにしてください。
 
 ただし、注釈・出典を貼るためにHTMLタグを利用します。
 
 - [cpprefjpにおける注釈・出典の貼り方](/start_editing/cite_note_ref.md)
 
-それ以外に本サイト内で使用しているHTMLタグは以下です：
-
-- アンカーを貼るために、`<a id="アンカー名">対象文字列</a>`のようなHTML5に基づく記法を利用している
-- 表内での改行のために、`<br/>`タグを利用している
-- 値の大きさを表現するために、上付き文字を表す`<sup>`タグを利用している
-- 添字を表現するために、下付き文字を表す`<sub>`タグを利用している
-
-その他、Markdown記法の制限として、以下のようなものがあります：
-
-- 表内で `|` (縦線、vertical line) を使用するために、文字参照 `&amp;#x7C;` を使用している
-- 箇条書きのインデントとして4スペースのみを許可している (2スペースでは正しくインデントされない)
 
 新規リファレンスを書くにあたって、雛形ページを用意していますので、そちらをベースにして編集作業を行ってください。
 
diff --git a/start_editing/.markdown_cpprefjp.md.swp b/start_editing/.markdown_cpprefjp.md.swp
diff --git a/start_editing/class_template_page.md b/start_editing/class_template_page.md
@@ -1,6 +1,6 @@
 # page_title (1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/comparison_operator_template_page.md b/start_editing/comparison_operator_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/concept_template_page.md b/start_editing/concept_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/cpo_template_page.md b/start_editing/cpo_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/function_template_page.md b/start_editing/function_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/header_template_page.md b/start_editing/header_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/lang_template_page.md b/start_editing/lang_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/markdown_cpprefjp.md b/start_editing/markdown_cpprefjp.md
@@ -1,10 +1,97 @@
-# cpprefjp特有の拡張構文
+# cpprefjpでのMarkdown記法の制限と拡張
 
 * [mathjax enable]
 
+
+## 概要
+cpprefjpでは、ドキュメントの記述にMarkdown記法を採用していますが、いくつかの制限があり、表現力が足りない部分は拡張記法を用意しています。
+
+
+## Markdown記法の制限
+### HTMLタグの制限
+cpprefjpでは、許可されたHTMLタグしか使用できません。
+
+- アンカーを貼るために、`<a id="アンカー名">対象文字列</a>`のようなHTML5に基づく記法を許可
+- 表内での改行のために、`<br/>`タグを許可
+- 値の大きさを表現するために、上付き文字を表す`<sup>`タグを許可
+- 添字を表現するために、下付き文字を表す`<sub>`タグを許可
+
+### ブロックコメントの制限
+
+実装に使用しているMarkdownパーサーによる制限で、以下のようなブロックコメントは使用できません。
+
+```
+<!--
+
+comment out text...
+
+-->
+```
+
+
+### 表内での縦線の制限
+
+表内で `|` (縦線、vertical line) を使用するために、文字参照 `&amp;#x7C;` を使用しています。
+
+
+### 箇条書きのインデントとして4スペースのみを許可する制限
+
+実装に使用しているMarkdownパーサーによる制限で、箇条書きのインデントとして4スペースのみを許可しています (2スペースでは正しくインデントされません)。
+
+```
+* てすと
+  * てすと2
+```
+
+これはcpprefjpではフラットなリストだと解釈されます。
+
+```
+* てすと
+    * てすと2
+```
+
+これなら正しく表示されます。
+
+
+### HTMLエンティティを使用できない制限
+```
+&reg;
+```
+のような書き方をすると、cpprefjpではエラーになります。HTML エンティティを使わず、以下のように書いてください。
+
+```
+®
+```
+
+
+## リストの前に空行が必要な制限
+```
+適当な文字列
+* リスト
+* リスト2
+```
+
+このような書き方をすると、cpprefjpでは以下の様な表示になります。
+
+```
+適当な文字列 * リスト * リスト2
+```
+
+通常の文字列に続いてリストを置く場合、空行を入れる必要があります。
+
+```
+適当な文字列
+
+* リスト
+* リスト2
+```
+
+
+## Markdown記法の拡張
+
 Markdownだけだと表現力が足りないため、cpprefjpでは構文を拡張しています。
 
-## 文章中のコード
+### 文章中のコードに関する拡張
 
 バッククォートによる文章中のコード指定では、バッククォート内の両端にスペースは使用できません。以下のようにスペースはバッククォートの外で使用すれば、コードとして連結されます。
 
@@ -17,7 +104,7 @@ Markdownだけだと表現力が足りないため、cpprefjpでは構文を拡
 式`f(a,` [`std::make_shared`](/reference/memory/make_shared.md)`<X>(x));`が有効である場合、それを呼び出す。
 
 
-## コードブロック
+### コードブロックに関する拡張
 
 \`\`\` と \`\`\` で挟むことで、複数行に渡るコードを書けます。
 
@@ -45,7 +132,7 @@ int main() {
 }
 ```
 
-## シンタックスハイライト
+### シンタックスハイライトの拡張
 
 コードブロック開始側の \`\`\` の後ろに言語名を書くことで、その言語に対応したハイライトが行われます。
 
@@ -73,7 +160,7 @@ int main() {
 }
 ```
 
-## exampleタグ
+### exampleタグの拡張
 
 includeとmain関数を含む**原則すべてのC/C++言語のコードブロック**には`example`タグをつけてください。  
 `example`タグが付いたコードブロックはその場で実際にコンパイル・実行することができるようになります。  
@@ -99,7 +186,7 @@ namespace std {
 }
 ```
 
-## プログラムの修飾
+### プログラムの修飾に関する拡張
 
 コードブロックの直後に特定の構文で記述することで、コードブロックの一部を修飾できます。
 
@@ -151,7 +238,7 @@ int main() {
     - `＜対象文字列＞`をイタリック体にします。
     - `＜引数＞`はありません。
 
-### グローバル修飾
+#### グローバル修飾
 
 全てのコードブロックでは、デフォルトの修飾が実行されます。
 これを **グローバル修飾** と呼びます。
@@ -172,7 +259,7 @@ int main() {
 
 グローバル修飾の一覧は [GLOBAL_QUALIFY_LIST.txt](https://github.com/cpprefjp/site/blob/master/GLOBAL_QUALIFY_LIST.txt) にあります。
 
-## 定義語
+### 定義語に関する拡張
 
 `GLOBAL_DEFINED_WORDS.json` に定義語を登録することができます。形式は `GLOBAL_DEFINED_WORDS.json` を参照して下さい。
 
@@ -184,7 +271,7 @@ int main() {
 
 `yomi` には平仮名およびアルファベットでその定義語の読みを指定します。現在は使用されていませんが将来的に定義語が増えてきた時に、用語集または索引ページを自動生成する時の並び替えに使われる予定です。
 
-## リンクの存在チェック
+### リンクの存在チェックに関する拡張
 
 CommonMark形式のリンクや独自拡張のプログラムの修飾`link`などで生成されるHTMLにリンクが埋め込まれるとき、リンク先がサイト内へのリンクだった場合、リンク先の存在チェックも行います。
 
@@ -221,7 +308,7 @@ Note: You can create /reference/foobar.md for editors_doc/specialized.md.
 Warning: [nolinked editors_doc/specialized.md] href "/reference/foobar.md.nolink (/reference/foobar.md.nolink)" found.
 ```
 
-## メタ情報
+### メタ情報を付加する拡張
 
 ページのどこか（通常はページタイトルの下）に `* ＜メタ情報＞[meta ＜メタ情報タイプ＞]` という構文で書くことで、メタ情報を記述できます。
 記述可能なメタ情報は以下の通りです。
@@ -250,7 +337,7 @@ Warning: [nolinked editors_doc/specialized.md] href "/reference/foobar.md.nolink
     * `* cpp23deprecated[meta cpp]` : C++23で非推奨になった機能
     * `* cpp23removed[meta cpp]` : C++23で削除された機能
 
-## 数式
+### 数式を記述する拡張
 
 cpprefjpでは、数式をLaTeX形式で記述できます。
 内部的には[MathJax](https://www.mathjax.org/)を利用しています。
@@ -298,14 +385,3 @@ p \log_{10}b&amp;\text{もし $b$ が $10$ の累乗の場合}\\
 \right.
 $$
 
-
-## 使用できないMarkdown / HTMLの機能
-- ブロックコメント (実装に使用しているMarkdownパーサーによる制限)
-    ```
-    <!--
-
-    comment out text...
-
-    -->
-    ```
-
diff --git a/start_editing/module_template_page.md b/start_editing/module_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/named_requirement_template_page.md b/start_editing/named_requirement_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。
diff --git a/start_editing/type-type_template_page.md b/start_editing/type-type_template_page.md
@@ -1,6 +1,6 @@
 # page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)
 
-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)
+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)
 
 (
   サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`# page_title (1行目の見出し1はページのタイトルです。修飾なしで記載してください)`
`2`	`2`
`3`		`-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)`
	`3`	`+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)`
`4`	`4`
`5`	`5`	`(`
`6`	`6`	`サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`# page_title ((1行目の見出し1はページのタイトルです。修飾なしで記載してください)`
`2`	`2`
`3`		`-([cpprefjpを編集するには](/start_editing.md) および [cpprefjp特有の拡張構文](specialized.md) を先に読んで下さい。)`
	`3`	`+([cpprefjpを編集するには](/start_editing.md) および [cpprefjpでのMarkdown記法の制限と拡張](markdown_cpprefjp.md) を先に読んで下さい。)`
`4`	`4`
`5`	`5`	`(`
`6`	`6`	`サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。`