nDiki : 組織内公開ワーキングノートサイト

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 で使う上では問題無かった。

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

[ 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 サイトは公開となるので、組織内で限定公開するには境界型セキュリティに頼ることになる。ゼロトラストと考えるなら、漏洩してはならない情報を書かないよう注意して使うべきだ。

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

[ 2月9日全て ]

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。

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

[ 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 も追加したくなってきた。

[ 2月24日全て ]

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

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

[ 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 も不利そうだ。公開サイトで使うメリットは少ないな。

[ 3月23日全て ]

2022年6月7日 (火)

Obsidian Publish サイトと MkDocs サイト

一般的な話のノートObsidian Publish サイトで全体公開していて、組織固有の話のノートObsidian + MkDocs を使った組織内公開ワーキングノートサイトで限定公開している。

限定公開ノートから全体公開ノートへのリンクをつけるのがいささか面倒。さしあたって roamlinks MkDocs プラグイン と md-condition Markdown エクステンションを使って

 [Naney](https://notes.naney.org/Notes/Naney)

 <!--- #if OBSIDIAN -->
 [[Naney]]
 <!--- #endif -->

とリンクしている。

ああ、この限定公開から全体公開にリンクする機能を欲するの、20年弱前から変わらないなあ。WikiEngine を自作していた時は InterWikiLink を実装していたんだっけ。

[ 6月7日全て ]

About

Process Time: 0.349541s / load averages: 3.63, 1.18, 0.67