HN 日本語サマリー

← 一覧へ戻る
Web開発

Shrimple – よりシンプルで、より親切なMarkdown代替

Shrimple – A Simpler, Nicer Markdown (qount25.dev)

16 pointsby usrbinenv26 コメント

要約

Shrimpleは、Markdownに代わる、よりクリーンで読みやすいマークアップ言語です。コードブロック、リンク、リスト、ヘッダーなどの機能をシンプルに記述でき、特にGo言語でコンパイルして使用します。また、Parse & Render辞書機能や静的サイトジェネレーター機能も備えています。

全文翻訳

Shrimple

より優れ、よりクリーンなMarkdownの代替。
入手する。

これはShrimpleドキュメントです。テキストドキュメントとしても、HTMLにレンダリングされた場合でも、クリーンで読みやすいように記述されています。

インストールと使用方法

コンパイルするにはGoコンパイラが必要です。

go build

その後、次のように実行します。

cat README | ./shrimple -s -w > README.html

-s または --default-css フラグはHTML出力にデフォルトのCSSを追加し、-w または --wrap フラグはページをHTMLでラップして完全なドキュメントを作成します。自分のウェブサイトに挿入する出力を生成したい場合は、これらのタグは必要ありません。

利用可能なオプションをすべて表示するには、./shrimple --help と入力してください。

リンクと脚注

リンクもすっきり見えるように作られています。インラインURL(長くなりがちで可読性を損なう可能性があります)でソースドキュメントを汚染する代わりに、非常にシンプル!なアイデアを使用します。リンクは参照している脚注からURLを取得します。

もちろん、通常の脚注[1]を追加することもできます。この場合、単語の横にある数字の小さなリンクが脚注セクションに移動します。

コード

コードブロックから始めましょう。以下の例を見てください。2つのifブロックの間に空行があっても、それらは1つの連続したコードブロックになります。

if err != nil {
    return -1
}

if err == nil {
    return 1
}

コードブロックは6スペースでインデントする必要があります。レンダリングされるとトリムされますが、最初の6スペース以降の余分なスペースは保持されます。### Goで始まるコードブロックの最初の行はオプションですが、コードブロックタグにHTMLクラスを追加します。これは、Prism.jsコードハイライターと組み合わせて使用すると、特定の言語で正しいコードハイライトが得られます。

fmt.Println("this is inline code") のようなインラインコードも使用できます。

リスト

Shrimpleでは、番号付きリストと箇条書きリストも作成できます。たとえば、箇条書きリストは次のようになります。

  • リストは右に2スペースインデントする必要があります
  • 各項目は、前の項目から空行で区切られている場合とそうでない場合があります。
  • リスト項目が長い場合、コンテンツを次の行に簡単に配置できます。その場合、後続の行はすべて、最初の行に揃えるために4スペースでインデントする必要があります。

番号付きリストも同様です。

  1. インデントは同じです - 2スペース。
  2. 後続の項目は通常通り番号を付けることができます(Markdownではすべて「1」にする必要がありますが、それとは異なります)。
  3. 特定の番号付きリスト項目の後続の行は、最初の行のピリオド「.」で揃える必要があります。
  4. 番号は連続している必要はありませんが、連続するように正規化されます。これはただうまくいくのです!

2種類のヘッダー

ヘッダーは「h1」と「h2」の2つのレベルタイプが許可されます。レベルはアンダースコア行の「太さ」によって決まります。===は「h1」用、---は「h2」用です。ヘッダーに関する重要なこと:実際のヘッダーに続く行は、常に少なくとも3文字の長さが必要です(これはハードコードされたルールです)。さもないと、上の行はヘッダーとしてレンダリングされません。

注釈は、大文字の単語(スペースなし)で始まり、オプションで句読点が続く行で始まります。この場合、それは「:」です。続く行は4スペースでインデントする必要があります。単語は「NOTES」である必要はなく、代わりに「SIDENOTE」や「ATTENTION」のようなものであることができます。単語自体は小文字に変換され、HTMLタグのCSSクラスとして出力されます。

注釈には空行(インデントなし)を含めることもできますが、その注釈の一部と見なされるためには、空行は(したがって4スペースでインデントされた)その注釈に属する非空行に囲まれている必要があります。

パース&レンダリング辞書の解析とレンダリング

これはShrimpleの最も強力な機能の1つです。元のドキュメントをさまざまな種類の奇妙な文字やHTMLで汚染する代わりに、テキストを書き、特定の単語や式の出現箇所をハイライトする必要があるときに、パース&レンダリング辞書を使用して定義します。リポジトリのルートディレクトリにあるparse_dictとrender_dictの2つのファイルを見て、次の段落の例を見てください。

この段落は、パースとレンダリング辞書の例です。word1とword2は下線が引かれ、word3とスペースを含む式は緑色になっていることに注意してください。しかし、ソースShrimpleドキュメントにはこれらの単語に対する追加のマークアップはありません。それらは単にパースとレンダリング辞書に基づいてピックアップされます。

Shrimpleにパースとレンダリング辞書を使用するように指示するには、-pと-rのCLI引数(「p」はパース用、「r」はレンダリング用)を使用します。

./shrimple ... -p path/to/parse_dict -r path/to/render_dict

静的ウェブサイトの生成

Shrimpleの目標の1つは、常にドキュメントページを生成できるようにすることでした。これはShrimpleの静的サイトジェネレーターによって可能になります。ソースファイル(Shrimple形式で記述)のディレクトリを取得し、各ファイルをHTMLドキュメントに変換して、すべて別のディレクトリに出力します。各ページには、オプションでメニューと下部に前の/次のナビゲーションリンクが含まれます。

仕組みを見てみましょう。次のようなディレクトリ構造があるとします。

StaticSite
|
'-- 
   StaticSite
   |
   1_Part_One
   |        |
   |        001_chapter_one 
   |        002_chapter_two 
   |        003_chapter_three 
   |
   2_Part_Two 
   |        |
   |        001_chapter_four
   |        002_chapter_five
   |
   3_chapter_six
   |
   4_chapter_seven

エントリ1_Part_Oneと2_Part_Twoはディレクトリです。残りはファイルです。ファイル名がそれが含むディレクトリと同じ場合、静的サイトが生成された後、index.htmlになります。ディレクトリ名とファイル名の先頭にある数字は、ナビゲーションとメニューリンクを生成するために必要な正しい順序を保証するためにあります。

同じファイル構造が、便宜のためにexamples/StaticSiteディレクトリに提供されています。静的ウェブサイトを生成するには、次のコマンドを使用します。

./shrimple -s -g -n -m examples/StaticSite StaticSite_out

そして、StaticSite_outディレクトリの中身を確認してください。一部のファイルに変更が加えられ、同じコマンドを再度実行した場合、Shrimpleは生成が必要なファイルのみを生成します。

提供されるオプションは次のとおりです。

  • -g または --generate-site は、ソースディレクトリから静的ウェブサイトを生成したいことをShrimpleに伝えます。
  • -s はすでに知っているでしょう - デフォルトのスタイルシートを追加しますが、-c または --css でカスタムスタイルシートを指定できます。
  • -n は、静的サイトジェネレーターに各ページの最下部に前の/次のナビゲーションリンクを追加するように指示します。
  • -m は、生成されたすべてのページへのリンクを含む、きれいにネストされたメニューも追加します。

メニューとナビゲーションのすべてのリンクは、ブラウザでファイル - 開くでページを開けば機能し、サーバーを必要としません。

脚注:

  1. 脚注は基本的に番号付きリスト項目です。
  2. ただし、ドキュメントのどこかに[n]を配置して参照できます(上記参照)。
  3. または、-> link [4]と言うことで、ドキュメント自体を汚染せずに脚注付きリンクを作成できます。
  4. https://qount25.dev/Shrimple/
  5. https://prismjs.com
  6. https://code.qount25.dev/qount25/Shrimple