Merge pull request #73 from afh/mkdocs

Switch to MkDocs and add client-side search and custom 404 page
ledger · Apr 29, 2023 · 4451190 · 4451190
2 parents a614f00 + d5b6614
commit 4451190
Show file tree

Hide file tree

Showing 24 changed files with 143 additions and 708 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,13 +1,7 @@
-*.hi
-*.o
-*.html
-site
-_*
-*.org
-snapshot.tar.gz
-*.log
-*.aes
-.DS_Store
+# NOTA BENE: source/css is generated from custom_theme/sass
+source/css
+# Files generated during build or development
+build
 result*
-vendor/
-.bundle/
+# Files specific to macOS
+.DS_Store
diff --git a/Gemfile b/Gemfile
diff --git a/Gemfile.lock b/Gemfile.lock
diff --git a/Makefile b/Makefile
@@ -16,6 +16,9 @@ ledger3.texi_repopath      := $(OWNER)/$(REPO)/$(LATEST)/doc
 ledger.1_repopath          := $(OWNER)/$(REPO)/$(LATEST)/doc
 ledger-mode.texi_repopath  := $(OWNER)/ledger-mode/master/doc
 
+install: source/css
+	mkdocs build
+
 docs: init sources pdf html
 
 pdf: $(PDF)
@@ -24,6 +27,11 @@ html: $(HTML)
 
 sources: $(SOURCES)
 
+.PHONY: source/css
+source/css: custom_theme/sass
+	python -c 'import sass; sass.compile(dirname=("$<", "$@"))'
+
+
 .PHONY: init
 init:
 	mkdir -p $(OUTPUT)

diff --git a/config.rb b/config.rb
diff --git a/source/layouts/layout.erb → custom_theme/main.html b/source/layouts/layout.erb → custom_theme/main.html
@@ -2,32 +2,42 @@
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title><%= current_page.data.title %></title>
+    <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title>
     <meta name="description" content="Website and documentation for the open source command-line double-entry accounting system named ledger">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <%= stylesheet_link_tag "site" %>
+    <link href="/css/site.css" rel="stylesheet">
   </head>
   <body>
     <main>
       <aside>
         <a href="https://git.ledger-cli.org/ledger" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><title>Fork me on GitHub</title><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a>
       </aside>
+
       <header>
         <nav>
-          <ul>
-            <li><a href="/">ledger</a></li>
-            <li><a href="index.html">Home</a></li>
-            <li><a href="features.html">Features</a></li>
-            <li><a href="docs.html">Docs</a></li>
-            <li><a href="download.html">Download</a></li>
-            <li><a href="contribute.html">Contribute</a></li>
-            <li><a href="https://wiki.ledger-cli.org/">Wiki</a></li>
-          </ul>
+        {% if nav|length>1 -%}<ul>
+          {% for nav_item in nav -%}
+            <li class="{% if nav_item.active %}current{% endif %}"><a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a></li>
+          {% endfor -%}
+          {%- block search_button %}
+            {%- if 'search' in config['plugins'] %}<li>{%- include "searchbox.html" %}</li>{%- endif %}
+          {%- endblock %}
+        </ul>{% endif -%}
         </nav>
       </header>
       <article>
-        <%= yield %>
+      {% block content %}
+        {{ page.content }}
+      {% endblock %}
       </article>
     </main>
+    {%- block scripts %}
+    <script>var base_url = '{{ base_url }}';</script>
+    <script src="{{ 'js/theme_extra.js'|url }}" defer></script>
+    <script src="{{ 'js/theme.js'|url }}" defer></script>
+    {%- for path in extra_javascript %}
+      <script src="{{ path }}" defer></script>
+    {%- endfor %}
+  {%- endblock %}
   </body>
 </html>
diff --git a/source/stylesheets/darkmode.css.scss → custom_theme/sass/darkmode.scss b/source/stylesheets/darkmode.css.scss → custom_theme/sass/darkmode.scss
diff --git a/source/stylesheets/doc.css.scss → custom_theme/sass/doc.scss b/source/stylesheets/doc.css.scss → custom_theme/sass/doc.scss
@@ -1,21 +1,21 @@
 @import url("darkmode.css");
 
 html {
-  background-color:var(--site-background-color);
+  background:var(--site-background-color);
 }
 
 body {
   color:var(--color);
-  background-color:var(--background-color);
+  background:var(--background-color);
 }
 
 h1, h2, h3, h4, div.example {
   color:var(--color);
 }
 
 div.example {
+  background:var(--example-background-color);
   filter:brightness(var(--example-brightness));
-  background-color:var(--example-background);
 }
 
 :link, a[href]:hover {
@@ -25,3 +25,4 @@ div.example {
 a[href]:visited {
   color:var(--visited-color) !important;
 }
+
diff --git a/source/stylesheets/site.css.scss → custom_theme/sass/site.scss b/source/stylesheets/site.css.scss → custom_theme/sass/site.scss
@@ -1,5 +1,18 @@
 @import url("darkmode.css");
 
+.current {
+  font-weight: bold;
+}
+
+div[role=search] {
+  display: inline-block;
+  position:absolute;
+  margin-top: -1em;
+  * {
+    display: inline-block;
+  }
+}
+
 body {
     color:var(--color);
     background:var(--background-color);
@@ -20,7 +33,7 @@ header {
 
     li {
       display:inline-block;
-      margin:0 2em 0 0;
+      margin:0 1.75em 0 0;
     }
 
    a { text-decoration:none; }
@@ -82,9 +95,9 @@ pre, code, tt {
     font-family:monospace;
 }
 
-pre.highlight {
+pre {
     margin:0 0 0 1em;
-    code {
+    code[class^="language-"] {
       padding:0.5em;
       display:inline-block;
       background:var(--highlight-code-background-color);
@@ -112,7 +125,7 @@ pre.highlight {
 
 @media screen and (max-width:765px) {
     header li {
-        margin:1em 2em 0 0;
+        margin:1em 1.75em 0 0;
     }
     nav li:has(a[href="/"]) {
       display:block;

diff --git a/custom_theme/search.html b/custom_theme/search.html
@@ -0,0 +1,15 @@
+{% extends "main.html" %}
+
+{% block content %}
+
+  <h1 id="search">{% trans %}Search Results{% endtrans %}</h1>
+
+  <form id="content_search" action="search.html">
+    <span role="status" aria-live="polite" class="ui-helper-hidden-accessible"></span>
+    <input name="q" id="mkdocs-search-query" type="text" class="search_input search-query ui-autocomplete-input" placeholder="{% trans %}Search the Docs{% endtrans %}" autocomplete="off" autofocus title="{% trans %}Type search term here{% endtrans %}">
+  </form>
+
+  <div id="mkdocs-search-results" class="search-results" data-no-results-text="{% trans %}No results found{% endtrans %}">
+  </div>
+
+{% endblock %}
diff --git a/custom_theme/searchbox.html b/custom_theme/searchbox.html
@@ -0,0 +1,5 @@
+<div role="search">
+  <form id ="rtd-search-form" class="wy-form" action="{{ base_url }}/search.html" method="get">
+      <input type="text" name="q" placeholder="{% trans %}Search{% endtrans %}" title="{% trans %}Type search term here{% endtrans %}" />
+  </form>
+</div>
diff --git a/flake.lock b/flake.lock