nDiki : MkDocs

2022年2月8日 (火)

Mkdocs Obsidian を試す

Obsidian Publish でノートをインターネット公開しつつ、それとは別に組織内で「公開で作業する」というコンセプトでノートを公開したいと模索している。

Obsidian forum ではいろいろな方法が提案されている。今回は以前使ったことがある静的サイトジェネレータ MkDocs を使った静的サイト生成を試してみることにした。

インストール: 

 pip3 install --upgrade pip
 pip3 install mkdocs
 pip3 install mkdocs-material
 pip3 install mkdocs-mermaid2-plugin
 pip3 install mkdocs-roamlinks-plugin
 pip3 install obs2mk
 pip3 install mkdocs-awesome-pages-plugin
 pip3 install git+git://github.com/Mara-Li/mkdocs-ezlinks-plugin
 pip3 install mdx_breakless_lists
 pip3 install git+git://github.com/Mara-Li/mkdocs-tooltipster-links-plugin#egg=mkdocs-tooltipster-links-plugin
 pip3 install mkdocs-embed-file-plugins
 pip3 install rich

次に雛形として Mkdocs Obsidian を取得する。

obs2mk コマンドを使うと Obsidian vault から MkDocs プロジェクトの docs を生成させられる。 

 obs2mk --git

そこそこいい感じだけれど出来合いのだと痒いところに手が届かないと思った時にちょっと辛いかなというのが印象かな。開発が止まることもあり得るし頼らない方が良さそう。

濁点のあるノートタイトルは予想通りうまくリンクにならなかった(Unicode 正規化形式の違いのせい)。

「Obsidian vault 内の一部のノートを MkDocs で静的サイト化する」するのではなく「MkDocs で静的サイト化するノートを Obsidian vault 内に置いて一緒に編集する (それらの Markdown ファイルは Obsidian のリンク機能などは使わない)」がいい気がしてきた。

2022年03月27日 追記

Unicode 正規化形式の違いの問題は Obsidian vault を Cryptomator vault の中に置いたことによるもので、 Obsidian + MkDocs で使う上では問題無かった。

[ 組織内公開ワーキングノートサイト ] [ 公開で作業する ]

[ permalink ]

今日のさえずり: 「テンプりん。」まだ生きていたんだ

[ permalink ]
[ 2月8日全て ]

2022年2月9日 (水)

MkDocs でワーキングノートを GitHub Pages にデプロイし公開する

Markdown で書いているノートを「公開で作業する」というコンセプトで社内で公開するのに、 GitHub Enterprise Server (以下 GHE) の GitHub Pages を使ってみることにした。

静的サイトジェネレータ MkDocs には GitHub Pages にデプロイする機能が入っている。GHE 上のリポジトリに対しても問題なく動いた。

手順1: MkDocs をインストール

 $ pip3 install mkdocs mkdocs-material

手順2: GHE でリポジトリを作成

GHE 上で notes リポジトリを作成する。プライベートでも OK。

手順3: MkDocs プロジェクトを作成する

 $ git clone git@example.com:Naney/notes.git
 $ cd notes
 $ git config user.name 'WATANABE Yoshimasa'
 $ git config user.email naney@example.com

MkDocs 設定ファイルと Markdown ファイルは既存の Obsidian vault の中にそれぞれ置いておき、シンボリックリンクしておくことにする。 

 $ ln -s /path/to/vault/Settings/mkdocs.yml

mkdocs.yml 内で以下を指定しておく。 

 docs_dir: /path/to/vault/notes

手順4: MkDocs ビルトインサーバでどのようなサイトになるか確認する

 $ mkdocs serve

を実行し、 Web ブラウザで http://127.0.0.1:8000/ に接続しどのように表示するか確認する。

手順5: GitHub Pages にデプロイする

 $ mkdocs gh-deploy

を実行すると gh-pages ブランチ上に静的サイトが生成され、リモートリポジトリに push してくれる。 GHE のリポジトリ側も自動で gh-pages ブランチを GitHub Pages で公開するように設定してくれる。びっくり。 https://example.com/pages/Naney/notes/ が公開 URL になる。

あとは Markdown ファイルを追加・更新・削除したら必要に応じて mkdocs serve で確認しつつ、 mkdocs gh-deploy していけば良い。

やってみると思ったよりお手軽だった。

GitHub Pages は公開

プライベートリポジトリでも GitHub Enterprise Server の GitHub Pages サイトは公開となるので、組織内で限定公開するには境界型セキュリティに頼ることになる。ゼロトラストと考えるなら、漏洩してはならない情報を書かないよう注意して使うべきだ。

[ 組織内公開ワーキングノートサイト ] [ 公開で作業する ]

[ permalink ]

今日のさえずり: MkDocs コマンド一発で GitHub Pages デプロイできちゃうのなかなか良かった

[ permalink ]
[ 2月9日全て ]

2022年2月14日 (月)

今日のさえずり: autolink-references-mkdocs-plugin これはめちゃくちゃ便利

[ permalink ]
[ 2月14日全て ]

2022年2月16日 (水)

MkDocs のページファイル名を YYYY-MM-DD-hhmmss.md にする

先週始めた MkDocs + GitHub Pages での組織内公開ワーキングノートサイト、ページファイル (Markdown ファイル)の名前を YYYY-MM-DD-タイトル.md のようにしていたのだけれど、やっぱり YYYY-MM-DD-hhmmss.md にすることにした。

日本語の入ったタイトルだと URL が長くなって、シェアする時に見辛いなと。 ナビゲーション上でページを新着順に並べる(mkdocs-awesome-pages-plugin での order:desc 指定を利用)のに、時刻まで入れておいた方が良いというのもある。

生成するページのタイトルは YAML front matter の title で指定しておけば OK。

[ ファイル名の先頭を日付にする ] [ 組織内公開ワーキングノート ]

[ permalink ]
[ 2月16日全て ]

2022年2月24日 (木)

組織内公開ワーキングノートサイト整備に合わせてノート構成と配置を考え直す

MkDocs + GitHub Enterprise Server の GitHub Pages で組織内公開ワーキングノートサイトをいい感じにできそうになってきた。

仕事用 Web ブラウザのスタートページ用ノート Things to Keep in Mind at Work ノートは MkDocs サイトの方に移すのが良さそう。

合わせて Things to Keep in Mind (at Work じゃない方) ノートや Top of Mind ノートも整理するかな。「最近考えていること」にフォーカスした Top of Mind ノートとは別に「今していること」を書き出しておく /now page も追加したくなってきた。

[ permalink ]

今日のさえずり: カレーコーナーのレードルが左右対称のになってた。今日は体はくねくねしながら盛り付けなくてすんだよ。

  • 11:49 カレーコーナーのレードルが左右対称のになってた。似非左利きとしてめちゃ嬉しい。 今日は体はくねくねしながら盛り付けなくてすんだよ。
  • 19:31 赤と青 #photography RICOH GR IIIx #GR #GRIIIx #GR3x https://t.co/jV7lUTlLF0
  • 25:00 2022年2月24日(木) やったこと - MkDocs サイトのナビゲーション見直し - 広告に関連するレイアウトの移動についての打ち合わせ
[ permalink ]
[ 2月24日全て ]

2022年2月25日 (金)

今日のさえずり: 社員食堂に日付限定で丼メニューが復活

  • 09:24 最高気温12℃予報とか、まだ今日はそれほどだろうなと思っていたんだけれど、電車内でダウンジャケット暑いぞ。
  • 11:41 社員食堂に日付限定で丼ぶりメニューが復活。懐かしいので注文。手軽なのが嬉しい。 毎日だと太りそうだけれど、たまになら。
  • 23:38 相手が1年会っていなかった友達だったらこんな自分の近況を話すだろうということを、自分のサイトに /now として書いておくと役に立つというので書いてみました。 https://www.naney.org/now
  • 23:47 PLAY Omotesando #photography RICOH GR IIIx #GR #GRIIIx #GR3x https://t.co/Gd66S49RwK
  • 25:00 2022年2月25日(金) やったこと - Web 日記のフッタを整理 - 仕事用 Web ブラウザ向け Things to Keep in Mind ノートの場所を Obsidian Publish サイトから MkDocs サイトへ - /now page を公開
[ permalink ]
[ 2月25日全て ]

2022年3月15日 (火)

今日のさえずり: 私を見て

[ permalink ]
[ 3月15日全て ]

2022年3月22日 (火)

Logseq でワーキングノートを GitHub Pages にデプロイし公開する

「公開で作業する」というコンセプトで Markdown で書いているノートを先月から MkDocs + GitHub Enterprise Server (以下 GHE) の GitHub Pages で公開してみている(記事)。

一昨日から使い始めたアウトライナー Logseq には graph (ページ群) を静的サイトとしてエクスポートする機能が標準でついている。思考中のメモを公開するのにうってつけそうだ。

MkDocs を使ったドキュメントベースの社内ノートサイトとは別に、アウトラインベースの社内ノートサイトを作ってみた。

手順1: ghp-import をインストール

MkDocs が GitHub Pages へのデプロイで使っている ghp-import をインストールする 

 $ pip3 install ghp-import

MkDocs をインストールしていればすでに入っている。

手順2: GHE でリポジトリを作成

GHE 上で graph リポジトリを作成する。プライベートでも OK。

手順3: Git リポジトリをローカルに clone する

Git リポジトリを clone したあと、Logseq graph をエクスポートするディレクトリとして site/ を作っておく。 

 $ git clone git@example.com:Naney/graph.git
 $ cd graph
 $ git config user.name 'WATANABE Yoshimasa'
 $ git config user.email naney@example.com
 $ mkdir site

手順4: Logseq で graph をエクスポートする

まずエクスポートするページ毎に [Make it public for publishing] しておくか、設定で [All pages public when publishing] をオンにしておく。

Logseq のメニューから [Export graph] を選び、 Export public pages を指定する。エクスポート先を選択するダイアログで前の手順で作成した site ディレクトリを選び、エクスポートする。

手順5: GitHub Pages にデプロイする

Git リポジトリディレクトリの中で以下を実行しデプロイする。 

 $ ghp-import --push --force --no-jekyll site

[ 組織内公開ワーキングノートサイト ] [ 公開で作業する ]

[ permalink ]
[ 3月22日全て ]

2022年3月23日 (水)

Logseq のジャーナルページ機能が心地よい

Logseq + GitHub Pages で昨日作成した組織内公開ワーキングノートサイト向け Logseq graph で実際にいろいろ書き始めてみた。

ジャーナルページに思い浮かんだことをスレッド的にダンプする

ジャーナル機能を使うかどうか迷ったけど使ってみている。 inbox として取りあえずさっと書けるのに加えて、関連して思い浮かんだことを子リストとしてスレッド的に書き足していけるのが心地よい。inbox として理想的だ。Tweet せずにここにダンプしておけば十分ではと思えてきた。

MkDocs + GitHub Page のページを移す

Markdown ファイルを順次移しながらチェック。

logseq-mermaid-plugin を使えば Logseq でも mermaid の図を入れられるが mermaid.ink という外部サイトでレンダリングさせる方式なのでそのまま使えない。fenced code block ではなく独自記法で囲む必要があるのもマイナスポイント。

セル内改行している表が Logseq ではうまく表示されなかったのでこれも移すのをいったん保留した。

Obsidian vault の中に Logseq graph を置くのをやめる

Logseq のスタイルで頻繁に graph を更新していくには Obsidian vault の中に置いておかない方がやはり良いな。組織内公開ワーキングノートサイト向け graph は外に出した。

ただそうすると Logseq のジャーナルと Obsidian のデイリーノートで2重管理が発生する。Logseq の backlink を活用するためには Logseq に書いておきたいし、後で参照するためのアーカイブとして Obsidian にも書いておきたい。 Logseq から Obsidian に転記したら 📋 でマークしてみたけれど、うまくいかない気がする。

Logseq でエクスポートした静的サイトは Google 検索エンジンにほとんどインデックスされない

公開ノートサイトにも Logseq を使ってみるのどうかと思ったけれど、 index.html にページデータを書き出した SPA になるのでページ数が増えた時に読み込みが遅くならないかなど懸念を感じた。 https://logseq.github.io/ はトップページしか Google 検索でヒットしていなさそうだし SEO も不利そうだ。公開サイトで使うメリットは少ないな。

[ permalink ]

今日のさえずり: 雨の日につま先が濡れない歩き方をあみだしたのは良いのだが

  • 12:22 Logseq のジャーナルページ機能が心地よいな。
  • 19:59 雨の日につま先が濡れない歩き方をあみだしたのは良いのだが、翌日モモが筋肉痛になる。
  • 25:00 2022年3月23日(水) したこと - MkDocs しているページをほぼ Logseq に移す
[ permalink ]
[ 3月23日全て ]

2022年3月27日 (日)

MkDocs のページファイル名をノートタイトルにする

Mkdocs Obsidian を試した時に濁点のあるノートタイトルがうまくリンクにならなかったこともあり YYYY-MM-DD-hhmmss.md をファイル名にしてきたけど、これだとファイル名だけでは中身が分からずやはり不便。

Unicode 正規化問題は Cryptomator が原因だったと分かったので、 Cryptomator vault から Markdown ファイルを外に出して、ノートタイトルをファイル名につけることにした。

MkDocs Roamlinks Plugin を入れて Obsidian と同じ表記でリンクできるようにすることで、リンクの億劫さが無くなった。

[ permalink ]

今日のさえずり: ファイル名の Unicode 正規化問題が解決した

[ permalink ]
[ 3月27日全て ]
月別インデックス

About

Naney Naneymx

Naney (なにい)です。株式会社ミクシィで SNS 事業の部長をしています。

※本サイトの内容は個人的見解であり所属組織とは関係ありません。

Process Time: 0.094938s / load averages: 0.45, 0.44, 0.47