Documentation

.github/workflows/build.yml

@@ -44,6 +44,8 @@ jobs:
         run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
         env:
           JEKYLL_ENV: production
+      - name: test HTML validity
+        run: bundle exec htmlproofer _site/ --disable-external true --enforce-https false --log-level :debug
       - name: Upload artifact
         if: ${{ github.ref == 'refs/heads/main' }}
         uses: actions/upload-pages-artifact@v1

.gitignore

@@ -5,4 +5,5 @@
 
 # build artifacts
 /.jekyll-cache/
+/.jekyll-metadata
 /_site/

Gemfile

@@ -11,4 +11,8 @@ end
 group :plugins do
   gem 'jekyll-sitemap', "~>1.4.0"
   gem 'jekyll-last-modified-at', "~>1.3.0"
+end
+
+group :test do
+  gem 'html-proofer', "~>4.4.3"
 end

Gemfile.lock

@@ -8,10 +8,21 @@ GEM
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
     eventmachine (1.2.7)
     ffi (1.15.5)
     forwardable-extended (2.6.0)
     google-protobuf (3.22.2-x86_64-linux)
+    html-proofer (4.4.3)
+      addressable (~> 2.3)
+      mercenary (~> 0.3)
+      nokogiri (~> 1.13)
+      parallel (~> 1.10)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
     http_parser.rb (0.8.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
@@ -49,10 +60,15 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
+    nokogiri (1.15.4-x86_64-linux)
+      racc (~> 1.4)
+    parallel (1.23.0)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     posix-spawn (0.3.15)
     public_suffix (5.0.1)
+    racc (1.7.1)
+    rainbow (3.1.1)
     rake (13.0.6)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
@@ -65,13 +81,18 @@ GEM
       rake (>= 10.0.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
     unicode-display_width (2.4.2)
     webrick (1.8.1)
+    yell (2.2.2)
+    zeitwerk (2.6.11)
 
 PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  html-proofer (~> 4.4.3)
   jekyll (~> 4.3.2)
   jekyll-last-modified-at (~> 1.3.0)
   jekyll-sitemap (~> 1.4.0)
@@ -80,4 +101,4 @@ RUBY VERSION
    ruby 3.0.0p0
 
 BUNDLED WITH
-   2.4.8
+   2.4.19

README.md

@@ -35,3 +35,11 @@ Exemple:
       \- about.html # title: "About"
 
 Toutes les pages présentes dans le dossier `items` sont automatiquement ajoutées à la **collection** : la liste des objets présentés sur le site.
+
+Pour que les pages de doc soient référencées dans le menu de navigation, ajouter sa catégorie ("tutorial" ou "guide") et son titre dans le header de la page.
+
+Exemple :
+    ---
+    title: Créer une visite guidée
+    category: tutorial
+    ---

_config.yml

@@ -22,19 +22,13 @@ defaults:
       lang: "en"
 
   - scope:
-      path: "fr/items"
-    values:
-      layout: "item"
-  - scope:
-      path: "en/items"
+      path: "*/items"
     values:
       layout: "item"
 
   - scope:
-      path: "fr/doc"
+      path: "*/doc"
     values:
       layout: "doc"
-  - scope:
-      path: "en/doc"
-    values:
-      layout: "doc"
+      type: doc
+

_data/doc.yml

@@ -0,0 +1,12 @@
+introduction:
+  fr: Introduction
+  en: Introduction
+guides:
+  fr: Guides techniques
+  en: Technical guides
+tutorials:
+  fr: Tutoriels
+  en: Tutorials
+references:
+  fr: Références
+  en: References

_data/nav.yml

@@ -6,4 +6,4 @@ doc/:
   en: Documentation
 about:
   fr: À propos
-  en: About
+  en: About

_includes/language_picker.html

@@ -6,7 +6,7 @@
 
 {% if  alt %}
 <li class="{{include.type}}" >
-  <a href="" class="dropdown-toggle {{include.classes}}" data-bs-toggle="dropdown" aria-haspopup="true" role="button" aria-expanded="false">
+  <a href="#" class="dropdown-toggle {{include.classes}}" data-bs-toggle="dropdown" aria-haspopup="true" role="button" aria-expanded="false">
     {{page.lang}}
     <span class="caret"></span>
     <span class="visually-hidden">(change language)</span>

_layouts/default.html

@@ -58,17 +58,16 @@
           <span class="navbar-toggler-icon"></span>
         </button>
         <div class="navbar-header me-3 p-2">
-          <a href="/{{page.lang}}/" class="navbar-brand" aria-label="ecorpus logo">
+          <a href="/{{page.lang | default: "fr" }}/" class="navbar-brand" aria-label="ecorpus logo">
             <img src="/assets/img/logo-ecorpus.png" alt="logo e-corpus" height="32">
             <span style="font-family: Noto Serif, serif;" class="px-2 text-light">eThesaurus</span> 
           </a>
         </div>
         <div class="collapse navbar-collapse" id="navbar-collapse-1">
           <ul class="nav navbar-nav ms-auto" role="menu">
             {%- for item in site.data.nav -%}
-
               <li class="nav-item">
-                <a class="nav-link" href="/{{ page.lang }}/{{ item[0] }}">{{ item[1][page.lang] }}</a>
+                <a class="nav-link" href="/{{ page.lang | default: "fr" }}/{{ item[0] }}">{{ item[1][page.lang] }}</a>
               </li>
             {%- endfor -%}
             {% include language_picker.html type="nav-item dropdown" classes="nav-link" %}

_layouts/doc-page.html

@@ -0,0 +1,9 @@
+---
+layout: doc
+---
+
+<section class="section section-center">
+    <div class="content">
+        {{ content }}
+    </div>
+</section>

_layouts/doc.html

@@ -1,12 +1,17 @@
 ---
-layout: page
+layout: default
 ---
 
-<main class="pt-5 main-grid">
-    <section class="section section-center">
-        <div class="content">
-            {{ content }}
+<div class="sidebar-layout main-dark">
+    <nav class="content-bar bg-faded navbar-dark navbar-expand-lg">
+        <button class="navbar-toggler dropdown-toggle my-3" type="button" data-bs-toggle="collapse" data-bs-target="#sidebar" aria-controls="sidebar" aria-expanded="true" aria-label="Toggle navigation">
+            <span>Navigation</span>
+        </button>
+        <div class="navbar-collapse flex-column align-items-stretch collapse show" id="sidebar" aria-expanded="false">
+            {% docnav %}
         </div>
-    </section>
-
-</main>
+    </nav>
+    <main class="content main-grid">
+        {{ content }}
+    </main>
+</div>

_plugins/doc_nav.rb

@@ -0,0 +1,139 @@
+# Copied from holusion.com build plugins (https://github.com/Holusion/holusion.com/blob/master/_plugins/dev_nav.rb)
+
+module Jekyll
+  module Tags
+    class DocNav < Liquid::Tag
+      @@uids = 1
+
+      def cache
+        @@cache ||= Jekyll::Cache.new("DocNav")
+      end
+      def getUid
+        @@uids += 1
+        return @@uids
+      end
+
+      def initialize(tag_name, markup, tokens)
+        super
+      end
+
+
+      # makes a tree of docs as a hash like :
+      # {
+      #   "fr" => {
+      #     "page_path" => { :title, :url, :children }
+      #   }
+      # }
+      def doc_tree(docs)
+        tree = { "fr" =>{}, "en" => {}}
+        docs.each do |doc|
+          next if doc.data["type"] != "doc"
+          match = /\/(?<lang>fr|en)\/doc\/((?<rest>.*)\/)?(?<last>(?!index)[^\/]+)/.match(doc.url)
+          next if ! match #skip if page does not match
+          lang = match["lang"]
+          parts = match["rest"]? match["rest"].split("/") : []
+          last_part = match["last"]
+
+          current_hash = tree[lang]
+
+          parts.each do |part|
+            #print "current hash :#{current_hash}"
+            current_hash[part] = {:children =>{}, :title => part } if not current_hash.has_key? part
+            current_hash = current_hash[part][:children]
+          end
+
+          current_hash[last_part] = {
+            :title => doc.data["title"],
+            :rank => doc.data.has_key?("rank")? doc.data["rank"] : 0,
+            :url => doc.url,
+            :children =>(current_hash.has_key?(last_part)) ? current_hash[last_part][:children]: {},
+            :visible => doc.data.has_key?("visible")? doc.data["visible"] : true
+          } if doc.data["visible"] != false
+        end
+
+        return tree
+      end
+
+      def render_item(path, item, active_uri)
+        uid = getUid
+
+        is_active = active_uri.include? path
+        title = item[:title] || path.split("/").last
+        url = item[:url] || ""
+
+        markup = %(<li class="list-group-item content-bar--link#{is_active ? " current" : ""}">)
+
+        if item[:children].empty?
+          markup += %(<a href="#{url}">#{title}</a>)
+        else
+          sorted_children = item[:children].sort_by { |key, val| val.has_key?(:rank)? val[:rank] : 0 }
+          child_nodes = sorted_children.map do |childKey, child|
+            render_item(path+"/#{childKey}", child, active_uri)
+          end
+
+          markup += %(
+            <a class="dropdown-toggle" role="button" data-proofer-ignore
+              data-bs-toggle="collapse"  aria-haspopup="true"
+              aria-expanded="#{is_active ? "true" : "false"}"
+              data-bs-target="#collapseList#{uid}"
+              aria-expanded="#{ is_active ? "true" : "false"}"
+              aria-controls="collapseList#{uid}">
+              #{title}
+            </a>
+          )
+
+          markup += %(
+            <ul class="collapse list-group list-group-flush content-bar-group--sub#{is_active ? " show" : ""}"
+              id="collapseList#{uid}"
+            >
+          )
+          if url and 0 < url.length
+            markup += %(
+              <li class="list-group-item content-bar--link#{url == active_uri ? " current": ""}">
+                <a href="#{url}">Introduction</a>
+              </li>
+            )
+          end
+          markup += child_nodes.join("\n")
+          markup += %(</ul>)
+        end
+
+        markup += %(</li>)
+        return markup
+      end
+
+      def render(context)
+        #global site variable
+        site = context.registers[:site]
+        page = context.registers[:page]
+        #replace variables with their current value
+
+        lang = page["lang"]
+        if not lang
+          raise SyntaxError, <<~END
+          Syntax Error in tag 'docnav' : require a lang to be set
+          END
+        end
+
+        docs_tree = cache.getset(site.time.to_s) do
+          doc_tree(site.pages)
+        end
+
+        html = %(<ul class="list-group list-group-flush content-bar-group--main">)
+
+        html += %(<li class="list-group-item content-bar--link#{ page["url"] == %(/dev/#{lang}/index) ? " current" : ""}">
+          <a href="/#{lang}/doc/">Introduction</a>
+        </li>)
+
+        sorted_localized_docs = docs_tree[lang].sort_by { |key, val| val.has_key?(:rank)? val[:rank] : 0 }
+        sorted_localized_docs.each do |key, doc|
+          next if doc[:children].empty?# do not render categories with no children for now
+          html += render_item(key, doc, page["url"])
+        end
+  	    return html+"</ul>"
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('docnav', Jekyll::Tags::DocNav)