Skip to content

Commit 3c36858

Browse files
stratselfstratself
committed
Deployed 2dc9e7e with MkDocs version: 1.6.1
1 parent 67ad3bd commit 3c36858

5 files changed

Lines changed: 53 additions & 32 deletions

File tree

‎index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -680,7 +680,7 @@
680680

681681

682682
<h1 id="welcome">Welcome</h1>
683-
<p>This is my personal repo to share some mkdocs tricks I figured out.</p>
683+
<p>This is my personal repo to share some mkdocs tricks I figured out. Right now it's just some macros.</p>
684684
<ul><li><a href='/install/'>Installation</a></li><li><a href='macros-reference/listfiles/'>Macros reference</a></li><li><a href='examples/'>Examples</a></li></ul>
685685

686686
<p>If you find a problem with the code or docs, please open an issue.</p>

‎install/index.html‎

Lines changed: 48 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -312,18 +312,27 @@
312312
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
313313

314314
<li class="md-nav__item">
315-
<a href="#install-macros" class="md-nav__link">
315+
<a href="#1-install-macros" class="md-nav__link">
316316
<span class="md-ellipsis">
317-
Install macros
317+
1. Install macros
318318
</span>
319319
</a>
320320

321321
</li>
322322

323323
<li class="md-nav__item">
324-
<a href="#create-mainpy" class="md-nav__link">
324+
<a href="#2-create-an-mkdocs-hook" class="md-nav__link">
325325
<span class="md-ellipsis">
326-
Create main.py:
326+
2. Create an mkdocs hook
327+
</span>
328+
</a>
329+
330+
</li>
331+
332+
<li class="md-nav__item">
333+
<a href="#3-create-mainpy" class="md-nav__link">
334+
<span class="md-ellipsis">
335+
3. Create main.py:
327336
</span>
328337
</a>
329338

@@ -730,18 +739,27 @@
730739
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
731740

732741
<li class="md-nav__item">
733-
<a href="#install-macros" class="md-nav__link">
742+
<a href="#1-install-macros" class="md-nav__link">
734743
<span class="md-ellipsis">
735-
Install macros
744+
1. Install macros
736745
</span>
737746
</a>
738747

739748
</li>
740749

741750
<li class="md-nav__item">
742-
<a href="#create-mainpy" class="md-nav__link">
751+
<a href="#2-create-an-mkdocs-hook" class="md-nav__link">
743752
<span class="md-ellipsis">
744-
Create main.py:
753+
2. Create an mkdocs hook
754+
</span>
755+
</a>
756+
757+
</li>
758+
759+
<li class="md-nav__item">
760+
<a href="#3-create-mainpy" class="md-nav__link">
761+
<span class="md-ellipsis">
762+
3. Create main.py:
745763
</span>
746764
</a>
747765

@@ -776,8 +794,8 @@
776794

777795

778796
<h1 id="installation">Installation</h1>
779-
<p>Most scripts here requires the <a href="https://github.com/fralau/mkdocs-macros-plugin">mkdocs-macro-plugin</a> which involves some setting up</p>
780-
<h2 id="install-macros">Install macros</h2>
797+
<p>Assuming you're inside your mkdocs project directory...</p>
798+
<h2 id="1-install-macros">1. Install macros</h2>
781799
<p>Install <strong>macros</strong> via <a href="https://mkdocs-macros-plugin.readthedocs.io/en/latest/#installation">mkdocs-macro-plugin</a> as well as required packages</p>
782800
<div class="highlight"><pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>mkdocs-macro-plugin<span class="w"> </span>mrkdwn_analysis<span class="w"> </span>pathspec<span class="w"> </span>python-frontmatter
783801
</code></pre></div>
@@ -786,8 +804,26 @@ <h2 id="install-macros">Install macros</h2>
786804
- search
787805
- macros
788806
</code></pre></div>
789-
<h2 id="create-mainpy">Create <code>main.py</code>:</h2>
790-
<p>In your project's root directory (<strong>not</strong> the docs directory), create a <code>main.py</code> file and copy the contents of main.py into it. </p>
807+
<h2 id="2-create-an-mkdocs-hook">2. Create an mkdocs hook</h2>
808+
<p>Add an mkdocs <a href="https://www.mkdocs.org/user-guide/configuration/#hooks">hook</a> e.g. <code>hooks.py</code> in your project's root directory (<strong>not</strong> the docs directory) with the following content:</p>
809+
<div class="tabbed-set tabbed-alternate" data-tabs="1:1"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">./hooks.py</label></div>
810+
<div class="tabbed-content">
811+
<div class="tabbed-block">
812+
<div class="highlight"><pre><span></span><code><span class="c1"># hooks.py</span>
813+
<span class="k">def</span><span class="w"> </span><span class="nf">on_nav</span><span class="p">(</span><span class="n">nav</span><span class="p">,</span> <span class="n">config</span><span class="p">,</span> <span class="n">files</span><span class="p">):</span>
814+
<span class="c1"># overrides config.nav for macros use</span>
815+
<span class="n">config</span><span class="o">.</span><span class="n">nav</span> <span class="o">=</span> <span class="n">nav</span>
816+
<span class="k">return</span> <span class="n">nav</span>
817+
</code></pre></div>
818+
</div>
819+
</div>
820+
</div>
821+
<p>This is important for use in <a href="../macros-reference/listnavs/">listnavs()</a>, as it allows the macro to receive nav events from mkdocs/other plugins.</p>
822+
<h2 id="3-create-mainpy">3. Create <code>main.py</code>:</h2>
823+
<p>In your project's root directory (<strong>not</strong> the docs directory), create a <code>main.py</code> file and copy the contents of <a href="https://github.com/skedastically/mkdocs-macro-gimmicks/blob/main/main.py">main.py</a> into it. </p>
824+
<p>With wget:</p>
825+
<div class="highlight"><pre><span></span><code>wget<span class="w"> </span>https://raw.githubusercontent.com/skedastically/mkdocs-macro-gimmicks/main/main.py
826+
</code></pre></div>
791827
<p>Now you can start using commands such as <code>{{ listfiles() }}</code></p>
792828
<p>If you already used macros with the file, simply append the scripts inside <code>def define_env(env):</code> to your file.</p>
793829
<h2 id="further-resources">Further resources</h2>

‎macros-reference/listnavs/index.html‎

Lines changed: 3 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -789,23 +789,8 @@ <h1 id="list-navigations">List navigations</h1>
789789
<p class="admonition-title">Nested listings are not supported (yet?)</p>
790790
</div>
791791
<h2 id="usage-with-awesome-nav">Usage with awesome-nav</h2>
792-
<p><code>listnavs()</code> can be used with <a href="https://github.com/lukasgeiter/mkdocs-awesome-nav">awesome-nav</a> with some tweaks:</p>
793-
<ol>
794-
<li>Add an mkdocs <a href="https://www.mkdocs.org/user-guide/configuration/#hooks">hook</a> e.g. <code>hooks.py</code> in your project's root directory (<strong>not</strong> the docs directory) with the following content:</li>
795-
</ol>
796-
<div class="tabbed-set tabbed-alternate" data-tabs="1:1"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">./hooks.py</label></div>
797-
<div class="tabbed-content">
798-
<div class="tabbed-block">
799-
<div class="highlight"><pre><span></span><code><span class="k">def</span><span class="w"> </span><span class="nf">on_nav</span><span class="p">(</span><span class="n">nav</span><span class="p">,</span> <span class="n">config</span><span class="p">,</span> <span class="n">files</span><span class="p">):</span>
800-
<span class="c1"># overrides config.nav for macros use</span>
801-
<span class="n">config</span><span class="o">.</span><span class="n">nav</span> <span class="o">=</span> <span class="n">nav</span>
802-
<span class="k">return</span> <span class="n">nav</span>
803-
</code></pre></div>
804-
</div>
805-
</div>
806-
</div>
807-
<p>Then you can configure both the plugins and this hook in <code>mkdocs.yml</code>. Remember to put macros <strong>after</strong> awesome-nav so the generated navigation can certainly pass through in order.</p>
808-
<div class="tabbed-set tabbed-alternate" data-tabs="2:1"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><div class="tabbed-labels"><label for="__tabbed_2_1">./mkdocs.yml</label></div>
792+
<p><code>listnavs()</code> can be used with <a href="https://github.com/lukasgeiter/mkdocs-awesome-nav">awesome-nav</a>, provided that you configured the hook and list the <code>macros</code> plugin <strong>after</strong> <code>awesome-nav</code>:</p>
793+
<div class="tabbed-set tabbed-alternate" data-tabs="1:1"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">./mkdocs.yml</label></div>
809794
<div class="tabbed-content">
810795
<div class="tabbed-block">
811796
<div class="highlight"><pre><span></span><code>hooks:
@@ -852,7 +837,7 @@ <h2 id="flags">Flags</h2>
852837
</tbody>
853838
</table>
854839
<h2 id="caveats">Caveats</h2>
855-
<p>If no <code>config.nav</code> object is found, <code>listnavs()</code> employs various heuristics to get a section's pages, as the <code>Navigation</code> object returned by <code>get_navigation</code> is very incomplete (see these issues: <a href="https://github.com/fralau/mkdocs-macros-plugin/issues/156">mkdocs-macros-plugin#156</a>, <a href="https://github.com/fralau/mkdocs-macros-plugin/discussions/198">mkdocs-macro-plugin#198</a>).</p>
840+
<p><code>listnavs()</code> employs various heuristics to get a section's pages, as the <code>Navigation</code> object returned by <code>get_navigation</code> is very incomplete (see these issues: <a href="https://github.com/fralau/mkdocs-macros-plugin/issues/156">mkdocs-macros-plugin#156</a>, <a href="https://github.com/fralau/mkdocs-macros-plugin/discussions/198">mkdocs-macro-plugin#198</a>).</p>
856841
<div class="footnote">
857842
<hr />
858843
<ol>

0 commit comments

Comments
 (0)