MkDocs

はじめに この記事では、「MKDocsでURLを書いたら自動でハイパーリンクさせる方法」について書いています。 MKDocsでドキュメントを書くことが最近多いのですが、その使い方を色々調べる中で「知ってたら便利そう」な小ネタを知ったのが記事を書いたきっかけでした。 自分に向けた備忘録でもありますが、「MKDocsでURLを書いたら自動でハイパーリンクさせたい」な人の一助になれば嬉しいです。 要点だけ ymlファイルに以下を追加する markdown_extensions: - pymdownx.magiclink 実際に試してみる まずは、特に気にせず以下のようにymlファイルを書いた際、UR…

はじめに この記事では、「MKDocsでKaTeXを用いて数式表示をする方法」について書いています。 MKDocsで数式も書けると使える場面が増えて便利だなと調べ、以前に紹介しました。 更に調べたところ、以前に紹介したものはMathJaxというエンジンを用いたもので、他にもKaTexというエンジンを用いてMKDocs上で数式を書く方法もあることが分かったので導入の仕方を調べ実際に試してみた結果を記事にしてみました。 自分に向けた備忘録でもありますが、「MKDocsで数式を表示したい」や「MKDocsでKaTeXを使いたい」な人の一助になれば嬉しいです。 要点だけ pip install mar…

はじめに この記事では、「MKDocsで数式を書く方法」について書いています。 最近MKDocsを使って資料を書く機会が多いのですが、数式を扱うことがある人なら、MKDocsで数式を書けると便利かと思います。 自分に向けた備忘録でもありますが、「MKDocsで数式を書きたい」な人の一助になれば嬉しいです。 本文 今、以下の数式（何が表示されるかは後ほど分かります）をMKDocsで表示させたいとします。 $$ \int^{b}_{a} f(x) dx $$ まずは何もしてない状態で、ymlファイルは以下のような記述です。 site_name: My Docs theme: name: 'mkdo…

はじめに この記事では、「MKDocsでMermaidを使う方法」について書いています。 最近MKDocsを使って資料を書く機会が多いのですが、テキストで様々な図表を書くことができるMermaidをMKDocsで使いたいときはどうするのだろうと思ったのが記事を書いたきっかけでした。 自分に向けた備忘録の意味もありますが、「MKDocsでMermaidを使ってみたい」な人の一助になれば嬉しいです。 要点だけ ymlファイルに以下の記述を足してください site_name: My Docs theme: name: 'material' markdown_extensions: - pymdown…

はじめに この記事では、「GitHub PagesをMKDocsで作ってみる方法」について書いています。 GitHub PagesをMKDocsで手軽に作ってみたいなぁと思ったのが記事を書いたきっかけでした。 自分に向けた備忘録の意味もありますが、「GitHub PagesをMKDocsで作ってみたい」な人の一助になれば嬉しいです。 方法 mkdocsのファイルを用意する GitHub Pagesを作るためのリポジトリを適当に用意してください。 そしてその中にMkDocsのファイルを作ります。 今回の私の場合、（邪道かもしれませんが）一旦mkdocs new)コマンドを実行し、生成されたものを…

Argo のようなおしゃれなDocを作ってみたいということでMaterial for MkDocsをローカルで作って触ってみたので、セッティングとかの備忘録がてら記事にしたいと思います。 実行環境 実行環境 - pyenv + pyenv-virtualenv Python Version - python 3.8.0 pyenv + pyenv-virtualenv で実行環境設定 既存の環境は汚したくないので新しいpython仮想環境を新規作成して、その上で実行するようにします。 # python ver インストール pyenv install 3.8.0 pyenv versions …

昨今、技術界隈でもポリコレが重要視されている気がする世の中です. GitHubのデフォルトブランチがmainブランチに変更されていますが、MkDocsではmasterブランチがデフォルトのままです. この場合、生成されたHTMLの編集リンクはmasterブランチが参照されるため、GitHubで管理されている場合は404ページが表示されてしまいます. そこで今回は、MkDocsでmainブランチの編集画面を開く設定を書いておきます. TL; DR mkdocs.ymlにedit_uri: edit/main/docs/ を追記する mainブランチの編集画面を開く 公式ドキュメントのedit_u…

MkDocsが便利なので、AWSでサーバーレスかつ認証付きでホスティングできないか試してみました。 MkDocsを題材にしてますが、静的ファイルのポスティングするなら流用できると思います。 やること コード 前提 デプロイしてみる 設定 AWSリソースのデプロイ MkDocsのドキュメントを配置 動作確認 参考URL やること Lambda@Edgeを使ってCognitoの最低限の認証を組み込みます。 コード こちらで公開していますのでcloneしてください。 github.com git clone https://github.com/yomon8/cognito-serverless-m…

はじめに MKDocsでドキュメントを作成中、コードブロックの書き方で少し気になったことがあったため、自分への備忘録として記事にしました。 コードブロックの書き方 コードブロックの書き方には2種類あるそうです。 Fenced code blocks これはMKDocs以外でもよく見かけるコードブロックの書き方です。 バッククオート(`)を使用して以下のように書きます ここはコードブロックです。 さて、この書き方はインデントできず、リスト項目、引用符などの内部にネストすることはできないことに注意してください。 indented code blocks この書き方は私は全く知りませんでした。 MK…

はじめに これは「Material for MkDocs」で配色を切り替えられるよう、手元で試したことをまとめ自分への備忘録として記事にしたものです。 カラースキームを切り替えられるようにする 早速ですが、mkdocs.ymlでテーマを以下のように書きました。 theme: name: material palette: - scheme: default toggle: icon: material/toggle-switch-off-outline name: ダークモードに切り替えます。 - scheme: slate toggle: icon: material/toggle-swit…

はじめに この記事では、「Material for MKDocでチェックリストを使う方法」について書いています。 最近Material for MKDocでドキュメントを書いているんですが、MKDocでチェックリストを書こうとしても下図（CheckListの項の部分）のように正しく表示されず、その解決策を探していたのが記事を書いたきっかけでした。 自分に向けた備忘録の意味もありますが、「同じようにMaterial for MKDocでチェックリストを書きたいけど書けなくて困ってる」な人の一助になれば嬉しいです。 解決策 以下のサイトに書かれていました。 dev.classmethod.jp m…

カラースキームの設定 カラースキームとは、ドキュメント全体の色設定みたいなものだとおもってもらえれば良いかと思います。 この設定は、ライトモードとダークモードの２種類の設定ができ、それぞれはmkdocs.ymlで以下のように記述します。 まずはライトモードです。 site_name: MkDocs_Test theme: name: material language: ja palette: scheme: default そしてダークモード site_name: MkDocs_Test theme: name: material language: ja palette: scheme: …