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
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.mddans un dossier remplace l’index automatique de ce dossier ; - les images référencées en
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 
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 :
generatelit la configuration, charge les notes, calcule les citations puis crée les index ;build_notetransforme un fichier en page (titre = nom du fichier, permalien déduit du chemin) ;build_indexproduit la liste des dossiers et des notes, déjà triée côté serveur ;find_citationsanalyse 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, sinondatedu 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: falsesupprime les boutons.
Un clonage de dépôt, ou un
rsyncsans-t, remet à zéro la date de modification des fichiers : le tri « récent » devient alors inutile pour les notes sans front matter.rsync -aconserve les dates ; sinon, ajouter undate: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_urlet 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érifierpermalink: /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.
