<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>MKDocs on D. Sébastien Taggart</title>
    <link>https://www.sebastientaggart.com/tags/mkdocs/</link>
    <description>Recent content in MKDocs on D. Sébastien Taggart</description>
    <generator>Hugo</generator>
    <language>en</language>
    <lastBuildDate>Sun, 04 Oct 2026 22:13:05 -0400</lastBuildDate>
    <atom:link href="https://www.sebastientaggart.com/tags/mkdocs/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>Setting Up and Configuring MKDocs with Docker Compose: A Complete Guide</title>
      <link>https://www.sebastientaggart.com/writing/setting-up-and-configuring-mkdocs-with-docker-compose-a-complete-guide/</link>
      <pubDate>Sat, 20 Aug 2022 08:24:57 -0500</pubDate>
      <guid>https://www.sebastientaggart.com/writing/setting-up-and-configuring-mkdocs-with-docker-compose-a-complete-guide/</guid>
      <description>&lt;p&gt;MKDocs is a powerful static site generator tailored specifically for crafting project documentation. With MKDocs, you can transform your Markdown files into professional, searchable, and visually appealing documentation sites with remarkable speed and ease. By leveraging Docker Compose, you encapsulate all dependencies, simplifying the installation, configuration, and maintenance of MKDocs across various development environments. This combination not only streamlines your documentation workflow but also makes it scalable and manageable over time.&lt;/p&gt;</description>
      <content:encoded><![CDATA[<p>MKDocs is a powerful static site generator tailored specifically for crafting project documentation. With MKDocs, you can transform your Markdown files into professional, searchable, and visually appealing documentation sites with remarkable speed and ease. By leveraging Docker Compose, you encapsulate all dependencies, simplifying the installation, configuration, and maintenance of MKDocs across various development environments. This combination not only streamlines your documentation workflow but also makes it scalable and manageable over time.</p>
<h2 id="step-1-prerequisites">Step 1: Prerequisites</h2>
<p>Before we dive into the setup, let’s ensure you have the essential tools ready to go: Docker and Docker Compose.</p>
<ol>
<li><strong>Install Docker:</strong> Start by following the instructions on <a href="https://docs.docker.com/get-docker/">Docker’s official website</a> to install Docker for your operating system.</li>
<li><strong>Install Docker Compose:</strong> Next, follow the <a href="https://docs.docker.com/compose/install/">Docker Compose installation instructions</a>.</li>
</ol>
<h2 id="step-2-create-a-project-directory-and-add-initial-files">Step 2: Create a Project Directory and Add Initial Files</h2>
<p>Let’s set up a dedicated space for your documentation.</p>
<ol>
<li>
<p><strong>Create a new directory</strong> for your project documentation. For example:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir my_docs_project
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> my_docs_project
</span></span></code></pre></div></li>
<li>
<p>Within this directory, you&rsquo;ll need to create two files:</p>
<ul>
<li><code>docker-compose.yml</code>: This file will define how Docker sets up MKDocs.</li>
<li><code>mkdocs.yml</code>: This is MKDocs’ configuration file.</li>
</ul>
</li>
</ol>
<h2 id="step-3-define-the-docker-composeyml-file">Step 3: Define the <code>docker-compose.yml</code> File</h2>
<p>In your <code>my_docs_project</code> directory, create the <code>docker-compose.yml</code> file. This is where you’ll specify the Docker service that will run MKDocs.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;3&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">mkdocs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l">squidfunk/mkdocs-material:latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">.:/docs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="s2">&#34;8000:8000&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l">mkdocs serve -a 0.0.0.0:8000</span><span class="w">
</span></span></span></code></pre></div><h3 id="breaking-it-down">Breaking It Down:</h3>
<ul>
<li><strong>image</strong>: This specifies the <code>squidfunk/mkdocs-material</code> Docker image, which includes MKDocs along with the highly popular Material theme.</li>
<li><strong>volumes</strong>: By mounting the current directory to <code>/docs</code> in the container, MKDocs can access your files and reflect changes in real-time.</li>
<li><strong>ports</strong>: This maps port 8000 on your local machine to port 8000 in the container, allowing you to access MKDocs at <code>http://localhost:8000</code>.</li>
<li><strong>command</strong>: Here, we instruct MKDocs to serve the documentation at <code>0.0.0.0:8000</code>.</li>
</ul>
<hr>
<h2 id="step-4-configure-mkdocs-in-mkdocsyml">Step 4: Configure MKDocs in <code>mkdocs.yml</code></h2>
<p>Next, create the <code>mkdocs.yml</code> configuration file in the same directory. This file dictates how MKDocs behaves and displays your documentation.</p>
<p>Here’s a sample <code>mkdocs.yml</code> configuration:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">site_name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;My Project Documentation&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">theme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;material&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">nav</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">Home</span><span class="p">:</span><span class="w"> </span><span class="l">index.md</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">About</span><span class="p">:</span><span class="w"> </span><span class="l">about.md</span><span class="w">
</span></span></span></code></pre></div><h3 id="configuration-insights">Configuration Insights:</h3>
<ul>
<li><strong>site_name</strong>: Sets the title of your site.</li>
<li><strong>theme</strong>: Specifies the theme to &ldquo;material&rdquo; (the one provided by the Docker image we used).</li>
<li><strong>nav</strong>: Defines the navigation structure of the site, linking each item to a corresponding Markdown file.</li>
</ul>
<hr>
<h2 id="step-5-create-sample-markdown-files">Step 5: Create Sample Markdown Files</h2>
<p>To see anything displayed, MKDocs needs some content. In your project directory, create the <code>index.md</code> and <code>about.md</code> files as specified in the navigation structure.</p>
<ul>
<li>
<p><strong>index.md</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># Welcome to My Documentation
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">This is the home page of the documentation for my project.
</span></span></code></pre></div></li>
<li>
<p><strong>about.md</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># About
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">This page provides information about the project and its purpose.
</span></span></code></pre></div></li>
</ul>
<h2 id="step-6-launch-mkdocs-with-docker-compose">Step 6: Launch MKDocs with Docker Compose</h2>
<p>With your configuration and Markdown files in place, it&rsquo;s time to get MKDocs up and running using Docker Compose:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker-compose up
</span></span></code></pre></div><p>Docker will pull the necessary image (if it&rsquo;s not already downloaded), create the container, and start MKDocs. Once it&rsquo;s running, navigate to <code>http://localhost:8000</code> in your web browser to view your documentation.</p>
<p>As you edit the Markdown files, MKDocs will automatically refresh the page to display your updates in real-time.</p>
<h2 id="step-7-building-a-static-site-with-docker-compose">Step 7: Building a Static Site with Docker Compose</h2>
<p>To create a static version of your documentation site, you can use the <code>mkdocs build</code> command within Docker. This command compiles your Markdown files into static HTML, ready for deployment on any web server.</p>
<ol>
<li>
<p>Run the following command to build the site:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker-compose run mkdocs mkdocs build
</span></span></code></pre></div></li>
<li>
<p>After the build process, you’ll find the generated static files in a <code>site/</code> directory within your project. You can then transfer these files to your preferred web server or hosting service.</p>
</li>
</ol>
<h2 id="advanced-configuration-options">Advanced Configuration Options</h2>
<p>Once MKDocs and Docker Compose are running smoothly, consider exploring some advanced configuration options in <code>mkdocs.yml</code>:</p>
<ul>
<li>
<p><strong>Enabling Search</strong>: MKDocs features a built-in search functionality that indexes your content automatically. Just ensure you’re using a theme that supports it (like Material).</p>
</li>
<li>
<p><strong>Adding Plugins</strong>: MKDocs supports various plugins, such as <code>mkdocs-material-extensions</code> for additional customization. To add plugins, simply update <code>mkdocs.yml</code> like so:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">plugins</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">search</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">markdownextradata</span><span class="w">
</span></span></span></code></pre></div></li>
<li>
<p><strong>Using Custom CSS</strong>: For those who wish to add a personal touch, you can include custom CSS to style your documentation further. Create a CSS file in your project (e.g., <code>extra.css</code>) and update <code>mkdocs.yml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">extra_css</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">extra.css</span><span class="w">
</span></span></span></code></pre></div></li>
<li>
<p><strong>Adding Code Syntax Highlighting</strong>: If your documentation includes code snippets, MKDocs can automatically apply syntax highlighting for numerous programming languages. This feature is enabled by default with the Material theme.</p>
</li>
</ul>
<hr>
<p>In conclusion, setting up MKDocs with Docker Compose is a straightforward process that equips you with a robust, scalable solution for creating and maintaining documentation. With Docker Compose, managing dependencies becomes a breeze, allowing you to run MKDocs in any environment and even generate static builds for web deployment. Once established, MKDocs offers a clean, responsive, and well-organized documentation experience, complete with search functionality and theme customization. So, let’s get documenting!</p>
]]></content:encoded>
    </item>
  </channel>
</rss>
