Post

📒 Notes Markdown dans Chirpy : site statique, tri et notes citées

Publier un dossier de notes Markdown (avec ou sans front matter) dans Jekyll Chirpy : index automatiques, fil d'Ariane, onglet, tri alphabétique ou récent et repère des notes citées dans les posts

Notes Markdown dans Chirpy : site statique, tri et notes citées

Voir aussi le post 🧪Jekyll thème chirpy

Objectif

Générer un site statique à partir de dossiers contenant des fichiers Markdown .md, sans modifier les notes (pas de front matter obligatoire), en gardant les liens vers les images, et l’intégrer au thème Chirpy :

  • une page d’index automatique pour chaque dossier (sous-dossiers et notes) ;
  • un fil d’Ariane sur chaque page ;
  • un onglet Notes dans la barre latérale ;
  • un tri alphabétique ou du plus récent, au choix du visiteur ;
  • un repère sur les notes citées dans les posts du blog, avec la liste des posts en bas de la note.

Principe

Élément Rôle
_notes/ dossiers et fichiers .md, tels quels
_config.yml bloc markdown_folders : dossiers lus, URL de base, tri, repère
_plugins/markdown_folders.rb générateur Jekyll : une page par note, un index par dossier
_tabs/notes.md onglet de la barre latérale, à l’URL /notes/
assets/css/jekyll-theme-chirpy.scss style du repère

Le titre d’une note est son nom de fichier, et son URL est déduite du chemin (minuscules, sans accents, tirets à la place des espaces). Un fichier Linux/Sauvegarde Borg.md devient /notes/linux/sauvegarde-borg/.

1. Sauvegarde et arrêt du service

Avant toute modification, sauvegarder le dossier du site :

1
cp -a ~/chirpy /chemin/sauvegardes/chirpy-$(date +%F)

Script /usr/local/bin/stop-chirpy, qui arrête le service Jekyll et supprime le dossier _site :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#!/usr/bin/env bash
set -euo pipefail

SERVICE_NAME="chirpy.service"
PATH_NAME="chirpy-rsync.path"     # facultatif : unité de synchronisation vers un serveur
SITE_DIR="$HOME/chirpy"

cd "$SITE_DIR"

systemctl --user stop "$PATH_NAME" || true
systemctl --user stop "$SERVICE_NAME" || true

for _ in {1..30}; do
  if systemctl --user is-active --quiet "$SERVICE_NAME"; then
    sleep 1
  else
    break
  fi
done

rm -rf "$SITE_DIR/_site"
1
sudo chmod +x /usr/local/bin/stop-chirpy

2. Configuration _config.yml

1
2
3
4
5
6
7
8
9
10
markdown_folders:
  dirs: [_notes]         # plusieurs dossiers possibles, fusionnés dans une seule arborescence
  base_url: /notes
  root_title: Notes      # titre de l'index racine
  breadcrumb: true       # fil d'Ariane dans le contenu
  sort: alpha            # ordre initial : alpha | recent
  sort_switch: true      # boutons de tri sur les index
  cited_flag: "📌"       # repère des notes citées dans les posts ; vide ou absent = désactivé
  defaults:
    layout: page

cited_flag accepte un emoji, une icône Font Awesome ('<i class="fas fa-link"></i>') ou une image ('<img src="/assets/img/icons/flag.png" alt="">').

3. Le dossier _notes

1
mkdir -p ~/chirpy/_notes

Copier dedans les dossiers et fichiers Markdown existants. Règles appliquées par le plugin :

  • le front matter est facultatif ; s’il existe, il l’emporte sur les valeurs par défaut ;
  • les dossiers et fichiers dont le nom commence par un point (.obsidian, .trash) sont ignorés ;
  • un fichier index.md dans un dossier remplace l’index automatique de ce dossier ;
  • les images référencées en ![](/images/Nom Image.png) sont corrigées (les espaces deviennent %20), car kramdown ne les comprend pas.

4. Le plugin complet

_plugins/markdown_folders.rb :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
# frozen_string_literal: true

require 'yaml'
require 'date'
require 'time'
require 'cgi'

module Jekyll
  # Transforme des dossiers de .md (avec ou sans front matter) en pages,
  # avec une page d'index automatique par dossier, un fil d'Ariane,
  # un tri alphabétique / récent et un drapeau sur les notes citées dans les posts.
  class MarkdownFoldersGenerator < Generator
    safe true
    priority :low

    Note = Struct.new(:names, :slugs, :folder_names, :folder_slugs, :index, :page, :date,
                      keyword_init: true)

    def generate(site)
      cfg         = site.config['markdown_folders'] || {}
      @site       = site
      @base_url   = (cfg['base_url'] || '/notes').chomp('/')
      @defaults   = cfg['defaults'] || { 'layout' => 'page' }
      @root_title = cfg['root_title'] || 'Notes'
      @breadcrumb = cfg.fetch('breadcrumb', true)
      @sort       = cfg['sort'].to_s == 'recent' ? 'recent' : 'alpha'
      @switch     = cfg.fetch('sort_switch', true)
      @flag       = cfg['cited_flag'].to_s.strip

      notes = Array(cfg['dirs'] || '_notes').flat_map { |d| load_dir(d) }
      return if notes.empty?

      # Notes citées dans les posts : drapeau dans les listes + liste en bas de note
      @cited = @flag.empty? ? {} : find_citations(site, notes)
      notes.each do |n|
        posts = @cited[(n.index ? n.folder_slugs : n.slugs).join('/')]
        next unless posts

        links = posts.map { |p| "[#{p.data['title']}](#{site.baseurl}#{p.url})" }.join(', ')
        n.page.content += "\n\n---\n\n#{@flag} *Cité dans le blog : #{links}*\n"
      end

      folders = collect_folders(notes)
      indexed = notes.select(&:index).map { |n| n.folder_slugs.join('/') }

      pages = notes.map(&:page)
      tabs  = site.collections.values.flat_map(&:docs).to_h { |d| [d.url, d] }

      folders.each do |key, folder|
        next if indexed.include?(key)

        page = build_index(folder, notes, folders)
        if (doc = tabs[page.data['permalink']])
          doc.content = "#{page.content}\n\n#{doc.content}" # l'onglet existant reçoit la liste
        else
          pages << page
        end
      end

      pages.each { |p| site.pages << p }
    end

    private

    # --- Lecture des fichiers -------------------------------------------

    def load_dir(dir)
      root = File.join(@site.source, dir)
      return [] unless Dir.exist?(root)

      Dir.glob(File.join(root, '**', '*.md')).sort.filter_map do |path|
        names = path.sub("#{root}/", '').sub(/\.md\z/, '').split('/')
        next if names.any? { |s| s.start_with?('.') } # .obsidian, .trash…

        build_note(path, names)
      end
    end

    def build_note(path, names)
      raw  = File.read(path, mode: 'r:bom|utf-8')
      data = {}
      body = raw

      if (m = Jekyll::Document::YAML_FRONT_MATTER_REGEXP.match(raw))
        begin
          data = YAML.safe_load(m[1], permitted_classes: [Date, Time]) || {}
          body = m.post_match
        rescue Psych::SyntaxError => e
          Jekyll.logger.warn 'markdown_folders:', "front matter invalide dans #{path} (#{e.message})"
        end
      end

      slugs        = names.map { |s| Utils.slugify(s, mode: 'latin') }
      folder_names = names[0..-2]
      folder_slugs = slugs[0..-2]
      index        = names.last.casecmp?('index')

      crumb   = breadcrumb(folder_names, folder_slugs, link_last: !index)
      content = fix_images(body)
      content = "#{crumb}\n\n#{content}" unless crumb.empty?

      if index
        permalink = url(folder_slugs)
        title     = folder_names.last || @root_title
        name      = folder_slugs.last || 'index'
      else
        permalink = url(slugs)
        title     = names.last
        name      = slugs.last
      end

      page = make_page(name, permalink, title, content, data)
      Note.new(names: names, slugs: slugs, folder_names: folder_names,
               folder_slugs: folder_slugs, index: index, page: page,
               date: note_date(data, path))
    end

    # --- Index de dossiers ----------------------------------------------

    def collect_folders(notes)
      folders = {}
      notes.each do |n|
        (0..n.folder_slugs.size).each do |i|
          slugs = n.folder_slugs[0...i]
          f = (folders[slugs.join('/')] ||= { names: n.folder_names[0...i], slugs: slugs, date: n.date })
          f[:date] = n.date if n.date > f[:date]
        end
      end
      folders
    end

    def build_index(folder, notes, folders)
      names = folder[:names]
      slugs = folder[:slugs]
      depth = slugs.size

      subs = folders.values
                    .select { |f| f[:slugs].size == depth + 1 && f[:slugs][0...depth] == slugs }
                    .map { |f| [f[:names].last, href(f[:slugs]), f[:date], cited?(f[:slugs], folder: true)] }
      files = notes.reject(&:index)
                   .select { |n| n.folder_slugs == slugs }
                   .map { |n| [n.names.last, href(n.slugs), n.date, cited?(n.slugs)] }
      subs  = sort_entries(subs)
      files = sort_entries(files)

      lines = []
      crumb = breadcrumb(names, slugs, link_last: false)
      lines << crumb << '' unless crumb.empty?
      lines << sort_switch << '' if @switch && subs.size + files.size > 1

      lines << '## Dossiers' << '' << html_list(subs) << '' unless subs.empty?
      lines << '## Notes' << '' << html_list(files) << '' unless files.empty?

      name = slugs.last || 'index'
      make_page(name, url(slugs), names.last || @root_title, lines.join("\n"), {})
    end

    # --- Notes citées dans les posts ------------------------------------

    # { "linux/borg" => [post, ...] } : notes et dossiers cités dans les posts
    def find_citations(site, notes)
      valid = {}
      notes.each do |n|
        full = n.index ? n.folder_slugs : n.slugs
        (1..full.size).each { |i| valid[full[0...i].join('/')] = true }
      end

      re   = %r{#{Regexp.escape(@base_url)}/([^\s)"'<>\]#?]+)}
      hits = {}
      site.posts.docs.each do |post|
        post.content.scan(re).flatten.each do |raw|
          segs = CGI.unescape(raw).sub(/\.(md|html)\z/, '').split('/').reject(&:empty?)
          key  = segs.map { |s| Utils.slugify(s, mode: 'latin') }.join('/')
          next unless valid[key]

          (hits[key] ||= []) << post unless hits[key]&.include?(post)
        end
      end
      hits
    end

    def cited?(slugs, folder: false)
      return false if @cited.empty?

      key = slugs.join('/')
      @cited.key?(key) || (folder && @cited.keys.any? { |k| k.start_with?("#{key}/") })
    end

    # --- Utilitaires ----------------------------------------------------

    # Date d'une note : last_modified_at, puis date du front matter, puis mtime du fichier
    def note_date(data, path)
      d = data['last_modified_at'] || data['date']
      case d
      when Time   then d
      when Date   then d.to_time
      when String then (Time.parse(d) rescue File.mtime(path))
      else File.mtime(path)
      end
    end

    # entries = [[libellé, lien, date, cité], ...]
    def sort_entries(entries)
      if @sort == 'recent'
        entries.sort_by { |label, _, date, _| [-date.to_f, label.downcase] }
      else
        entries.sort_by { |label, _, _, _| label.downcase }
      end
    end

    def html_list(entries)
      items = entries.map do |label, link, date, cited|
        flag = cited ? %(<span class="note-flag" title="Cité dans le blog">#{@flag}</span> ) : ''
        %(<li data-name="#{CGI.escapeHTML(label.downcase)}" data-date="#{date.to_i}">) +
          %(#{flag}<a href="#{link}">#{CGI.escapeHTML(label)}</a></li>)
      end
      %(<ul class="md-sortable">\n#{items.join("\n")}\n</ul>)
    end

    def sort_switch
      <<~HTML
        <style>.md-sort button{margin-right:.4rem;padding:.15rem .7rem;border:1px solid var(--main-border-color,#ccc);border-radius:.4rem;background:none;color:inherit;cursor:pointer}.md-sort button.active{font-weight:bold;border-color:currentColor}</style>
        <p class="md-sort">Tri : <button type="button" data-sort="alpha">A → Z</button><button type="button" data-sort="recent">Plus récent</button></p>
        <script>
        (function () {
          var KEY = 'md-sort', mode = '#{@sort}';
          try { mode = localStorage.getItem(KEY) || mode; } catch (e) {}
          function apply(m) {
            document.querySelectorAll('ul.md-sortable').forEach(function (ul) {
              var li = [].slice.call(ul.children);
              li.sort(function (a, b) {
                if (m === 'recent') { var d = b.dataset.date - a.dataset.date; if (d) return d; }
                return a.dataset.name.localeCompare(b.dataset.name);
              });
              li.forEach(function (x) { ul.appendChild(x); });
            });
            document.querySelectorAll('.md-sort button').forEach(function (b) {
              b.classList.toggle('active', b.dataset.sort === m);
            });
            try { localStorage.setItem(KEY, m); } catch (e) {}
          }
          document.querySelectorAll('.md-sort button').forEach(function (b) {
            b.addEventListener('click', function () { apply(b.dataset.sort); });
          });
          apply(mode);
        })();
        </script>
      HTML
    end

    def make_page(name, permalink, title, content, data)
      page = PageWithoutAFile.new(@site, @site.source, '', "#{name}.md")
      page.content = content
      page.data.merge!(@defaults)
      page.data['title']     = title
      page.data['permalink'] = permalink
      page.data.merge!(data) # le front matter, s'il existe, l'emporte
      page
    end

    def url(slugs)
      slugs.empty? ? "#{@base_url}/" : "#{@base_url}/#{slugs.join('/')}/"
    end

    def href(slugs)
      "#{@site.baseurl}#{url(slugs)}"
    end

    def breadcrumb(names, slugs, link_last:)
      return '' unless @breadcrumb

      items = [[@root_title, []]] + names.each_index.map { |i| [names[i], slugs[0..i]] }
      return '' if items.size == 1 && !link_last

      items.each_with_index.map do |(label, s), i|
        i == items.size - 1 && !link_last ? label : "[#{label}](#{href(s)})"
      end.join(' › ')
    end

    # kramdown ne comprend pas les espaces dans ![](/images/Nom Image.png)
    def fix_images(text)
      text.gsub(%r{(!\[[^\]]*\]\()(/images/[^)"]*)\)}) do
        "#{Regexp.last_match(1)}#{Regexp.last_match(2).gsub(' ', '%20')})"
      end
    end
  end
end

Les points à retenir :

  • generate lit la configuration, charge les notes, calcule les citations puis crée les index ;
  • build_note transforme un fichier en page (titre = nom du fichier, permalien déduit du chemin) ;
  • build_index produit la liste des dossiers et des notes, déjà triée côté serveur ;
  • find_citations analyse le contenu des posts (voir plus bas) ;
  • si un onglet existe déjà à la même URL (/notes/), la liste lui est injectée plutôt que de créer une page en double.

5. L’onglet Notes dans la barre latérale

Dans Chirpy, les entrées de la barre latérale sont les fichiers de _tabs/, classés selon order. L’accueil est codé en dur et reste premier.

_tabs/notes.md :

1
2
3
4
5
6
---
title: Notes
icon: fas fa-book
order: 3
permalink: /notes/
---

L’icône peut être n’importe quelle icône Font Awesome gratuite (fas fa-book, fas fa-folder-open, fas fa-sticky-note…). Les autres onglets sont décalés :

Fichier order
_tabs/categories.md 1
_tabs/tags.md 2
_tabs/notes.md 3
_tabs/archives.md 4
_tabs/about.md 5

Le corps de _tabs/notes.md peut rester vide, ou contenir un texte d’introduction placé sous la liste.

6. Tri alphabétique ou plus récent

Chaque index propose deux boutons : A → Z et Plus récent.

  • Le tri initial est fait côté serveur selon sort, donc l’ordre est correct même sans JavaScript.
  • Les boutons réordonnent la liste dans le navigateur, et le choix est mémorisé (localStorage) pour tous les index.
  • Date d’une note : last_modified_at, sinon date du front matter, sinon date de modification du fichier. Pour un dossier, c’est la date de sa note la plus récente.
  • À égalité de date, l’ordre alphabétique départage.
  • sort_switch: false supprime les boutons.

Un clonage de dépôt, ou un rsync sans -t, remet à zéro la date de modification des fichiers : le tri « récent » devient alors inutile pour les notes sans front matter. rsync -a conserve les dates ; sinon, ajouter un date: aux notes.

7. Repérer les notes citées dans le blog

Le but : voir au premier coup d’œil, dans les listes, quelles notes sont citées par un post.

Ce qu’on fait

Rien dans la note. Il suffit de mettre, dans un post, un lien vers l’URL de la note :

1
Voir ma note [Sauvegarde Borg](/notes/linux/sauvegarde-borg/).

Un lien HTML (<a href="/notes/...">) fonctionne aussi.

URL d’une note

Fichier dans _notes Lien à mettre dans le post
Linux/borg.md /notes/linux/borg/
Linux/Sauvegarde Borg.md /notes/linux/sauvegarde-borg/
Réseau/Schéma VPN.md /notes/reseau/schema-vpn/

Ce que fait le plugin

  • Il lit le contenu de tous les posts, repère les liens commençant par base_url et les normalise comme les permaliens (majuscules, accents et ancres sont tolérés).
  • Les notes citées reçoivent le repère dans les listes, et leur dossier aussi.
  • En bas de chaque note citée s’affiche la ligne « Cité dans le blog : » avec le lien vers le ou les posts.
  • Le repère est écrit à côté du lien, mais le tri ne lit que le nom du fichier : les deux tris ne changent pas.

CSS

À la fin de assets/css/jekyll-theme-chirpy.scss :

1
2
.note-flag { margin-right: .3em; }
.note-flag img { height: 1em; width: auto; vertical-align: -0.125em; }

Lister les liens depuis le terminal

1
2
3
4
cd ~/chirpy
grep -rnoP "/notes/[^\s)\"'<>#?\]]+" _posts          # fichier:ligne:lien
grep -rhoP "/notes/[^\s)\"'<>#?\]]+" _posts | sort -u  # notes citées, sans doublon
grep -rhoP "/notes/[^\s)\"'<>#?\]]+" _posts | sort | uniq -c | sort -rn   # nombre de citations

Comparer avec ce que le plugin a réellement marqué :

1
grep -rhoP 'note-flag"[^>]*>[^<]*</span> <a href="\K[^"]+' _site/notes | sort -u

Seuls les posts publiés (_posts) sont analysés, pas les brouillons ni les pages. Un lien construit par Liquid à partir d’une variable n’est pas détecté.

8. Lancement du service

Script /usr/local/bin/start-chirpy :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/usr/bin/env bash
set -euo pipefail

SERVICE_NAME="chirpy.service"
PATH_NAME="chirpy-rsync.path"     # facultatif
SITE_DIR="$HOME/chirpy"
JEKYLL_BIN="$HOME/gems/bin/jekyll"

cd "$SITE_DIR"

export GEM_HOME="$HOME/gems"
export GEM_PATH="$HOME/gems"
export PATH="$HOME/gems/bin:/usr/local/bin:/usr/bin:/bin"

"$JEKYLL_BIN" build

systemctl --user start "$PATH_NAME" || true
systemctl --user start "$SERVICE_NAME" || true
1
sudo chmod +x /usr/local/bin/start-chirpy

Cycle de travail après chaque modification du plugin ou de la configuration :

1
2
stop-chirpy
start-chirpy

9. Vérifications

1
2
ls ~/chirpy/_site/notes/                                   # pages générées
grep -rc 'class="note-flag"' ~/chirpy/_site/notes/ | grep -v ':0'   # index où un repère existe

Dans le navigateur : ouvrir /notes/, naviguer dans un dossier, vérifier le fil d’Ariane, les deux boutons de tri, et le repère sur une note citée dans un post.

10. Pièges rencontrés

  • Cache du navigateur. Chirpy installe un service worker qui garde les pages : après une modification, rechargement forcé (Ctrl+Maj+R), ou Unregister du service worker et Clear site data dans les outils de développement. La navigation privée est le test le plus rapide.
  • Permalien dupliqué. Si /notes/ apparaît en double dans le build, l’URL de l’onglet ne correspond pas à celle de l’index racine : vérifier permalink: /notes/ dans _tabs/notes.md.
  • Dates de modification. Voir la remarque du chapitre 6 : conserver les dates avec rsync -a.
  • Liens avec accents ou espaces. Dans les posts, utiliser l’URL générée (minuscules, tirets), pas le nom du fichier. Le plugin normalise les majuscules et les accents, mais pas les autres différences d’orthographe.
  • Sauvegarde du plugin. Avant de le modifier : cp _plugins/markdown_folders.rb ~/markdown_folders.rb.bak.
Cet article est sous licence CC BY 4.0 par l'auteur.