Markdown

Ressources :

Journaux liées à cette note :

Première description du gestionnaire de projet de mes rêves #projet-24, #idée, #project-management

Introduction

Cela fait depuis 2022 que je souhaite prototyper un outil de gestion de tâches (issues) avec certaines fonctionnalités que je n'ai trouvées dans aucun outils Open source ou closed-source.

En novembre 2022, j'ai commencé le tout début d'un modèle de données PostgreSQL, mais je n'ai pas continué.

Je souhaite, dans cette note, présenter mon idée de prototype, présenter les fonctionnalités que j'aimerais implémenter.

Nom du projet : Projet 24 - Prototyper le gestionnaire de projet de mes rêves

Ces idées de fonctionnalité sont tirées de besoin personnel que j'ai rencontré depuis 2018, dans mes différents projets professionnel en équipe.

Pour réduire mon temps de rédaction de cette note et la publier au plus tôt, je ne souhaite pas détailler ici l'origine de ces besoins.
Je souhaite juste décrire quelques fonctionnalités que je souhaite et quelque détail technique sans expliquer l'origine de mon besoin.

Sources d'inspiration

Mes principales sources d'inspiration :

Je me projette d'utiliser Projet 24 dans les framework de gestion de projets suivants :

Ainsi qu'avec la technologie sociale Sociocratie 3.0.

Liste de fonctionnalités en vrac

  • Permettre d'importer / exporter une ou plusieurs issues dans un format de fichier YAML.
    • Permettre d'importer / exporter ces fichiers via Git.
    • Permettre l'utilisation de branche : création, suppression, merge de branches.
    • Permettre la gestion des branches via l'interface web.
    • Visualisation web des diff entre deux branches.
    • Permettre de commit ou créer des snapshots d'une branche.
  • Permettre d'attribuer à une issue une estimation basse et haute de temps d'implémentation.
  • Permettre d'activer un Hill Charts sur toute issue.
  • Permettre d'indiquer un niveau d'approximation d'une issue
  • Permettre aux lectures d'une issue d'indiquer leur niveau de compréhension de l'issue
  • Permettre de configurer la taille maximum en mots d'une issue. Pour forcer un certain niveau de synthèse.
  • Permettre de calculer le poids d'une issue en faisant la somme basse et haute de toutes ses dépendances.
  • Système inspiré de Tinder pour prioriser les issues. L'application présente deux issues choisies selon un algorithme Elo et invite l'utilisateur à désigner celle qu'il considère comme prioritaire.
  • Implémenter un système de tags d'issues personnalisés où chaque utilisateur peut créer ses propres étiquettes. La visibilité de ces tags serait configurable : mode privé pour un usage personnel ou mode partagé pour les rendre disponibles aux autres utilisateurs.
  • Permettre de créer des portfolios d'issue par utilisateurs.
  • Pas de séparation des entités Epic (gestion de projet logiciel) / Issue contrairement à ce que fait GitLab.
  • Permettre d'utilisation d'une extension Browser pour enrichir les pages GitHub, GitLab, Linear ou Forgejo avec les fonctionnalités de Projet 24.
  • Permettre au Projet 24 d'améliorer une instance privé Forgejo avec un wrapper HTTP.
  • Système de dashboard pratiquement identique à GitHub projects.
  • Système de commentaire comme GitHub, mais avec un système de thread.
  • Support de wikilink et alias au niveau de toutes les ressources texte.
  • Support d'une fonctionnalité de publication de notes éphémères attachées à chaque utilisateur.
  • Permettre la création d'issues ou de notes "flottantes". Une issue "flottante" n'appartient à aucune ressource spécifique — elle n'est rattachée ni à un projet, ni à un groupe. Cette fonctionnalité me semble essentielle et je compte la détailler dans une note dédiée prochainement.
  • Proposer une extension Browser qui détecte automatiquement les issues liées à l'URL de la page actuelle. Cela permettrait d'accéder rapidement aux issues ou notes "flottantes" selon le contexte de navigation.
  • Très bon support Markdown, contrairement aux implémentations de Slack, Notion ou Linear. Il devrait être possible de basculer entre le mode d'édition riche et le mode markdown. Le contenu copié doit générer du markdown valide dans le presse-papier.
  • Respect strict des conventions Web : permettre l'ouverture de toutes les pages dans un nouvel onglet, etc.
  • Mettre l'accent sur la performance de rendu des pages. Implémenter en priorité un système de métriques pour mesurer les temps de rendu.
  • Proposer un système de génération de titre d'issue et de tag basé sur un LLM.
  • Mettre en place un système qui utilise un LLM pour proposer automatiquement des titres d'issues et des tags.
  • Alimenter une base de données vectorielle avec les descriptions d'issues et leurs commentaires pour activer la recherche sémantique.

Expérience utilisateur

Comme SilverBullet.mb, un outil fait dans un premier temps pour les hackers.

Détails techniques

  • Stockage dans Elasticsearch pour faciliter les recherches par tags et plain text.
  • Utilisation de nanoid de 5 caractères pour identifier les issues.
  • Utilisation de Git hook pre-receive côté serveur pour importer des données (issues, notes, etc)

2026-04-02 : étudier Beads comme source d'inspiration ou outil à intégrer.

Aggregator - Backup Numeric Conversation System #backup, #idée

Ce matin, j'ai eu l' #idée et l’envie de créer une appli d'archivage et de centralisation de toutes mes conversations numériques.

L'objectif ? Rassembler en un seul endroit, dans une interface web minimaliste, toutes mes discussions provenant de :

Le support des threads serait utile pour Mattermost et les mails. J'aimerais pouvoir sauvegarder tous ces messages au format brut original et en Markdown. Une fonction pour partager un message ou un thread serait aussi sympa.

Pour la persistance des données, je pense utiliser ElasticSearch avec son moteur vectoriel. Un LLM pourrait assigner automatiquement des tags à chaque conversation. J'aimerais que l'interface web soit minimaliste, orientée vitesse et exploration.

Pour la postérité, toutes ces données devraient être exportées en continu dans un Object Storage, sous un format YAML facilement compréhensible.

Je me demande si ce type d’application existe en Open source ou closed-source 🤔.

User Style Stylus pour désactiver les popups de suggestion automatique d'emojis sur Discourse, GitHub et GitLab #firefox

En 2016, Philippe Lafoucrière m'a appris que contrairement aux règles de typographie française, en typographie anglaise, il ne faut pas placer d'espace avant le caractère deux points :.
Je pense d'ailleurs que cette différence est peu connue par les Français et inversement.

Une des conséquences malheureuses de cette différence est la présence généralisée d'une popup de suggestion automatique d'émojis après la séquence <espace>: dans les éditeurs de texte Markdown. Cette fonctionnalité est activée par défaut, sans option pour la désactiver, par exemple, dans GitHub, GitLab ou Discourse.

Exemple :

En 2022, j'ai implémenté et publié un User Styles pour Firefox (maintenant LibreWolf) basé sur Stylus pour désactiver cette autosuggestion automatique d'émojis sur GitHub, GitLab.

Je viens d'ajouter une règle pour Discourse.

Voici ces règles exécutées par Stylus (le fichier) :

@-moz-document regexp("http.*gitlab.*") {
    .atwho-container #at-view-58 {
        display: none !important;
    }
}

@-moz-document domain("github.com") {
    [class^="AutocompleteSuggestions"] {
        display: none !important;
        visibility: hidden !important;
    }
}

@-moz-document regexp(".*discourse.*"), regexp(".*discussion.*") {
    .autocomplete.ac-emoji {
        display: none !important;
    }
}

Comment l'installer ?

Je vais essayer de rassembler mes User Styles dans ce dossier : https://github.com/stephane-klein/dotfiles/tree/main/userstyles.

Journal du mardi 25 février 2025 à 09:35 #Doctrine, #documentation, #shell, #terminal, #dev-kit, #markdown

Dans cette note, je souhaite décrire et expliquer comment j'intègre des sessions de terminal dans des documentations.

Convention mainstream que j'ai adoptée

Je suis la convention mainstream suivante pour représenter des sessions terminal (de type bash, zsh…) au format Markdown :

Première partie :

$ echo "Hello, world!"
Hello, world!

$ ls -l
total 0
-rw-r--r-- 1 user user 0 Feb 25 10:00 file.txt

Seconde partie :

$ sudo su
# systemctl restart nginx 
$ exit

$ uptime # Affiche l'uptime
uptime 10:00:00 up 1 day, 2:45, 1 user, load average: 0.15, 0.10, 0.05

Les lignes commençant par $ ou # indiquent les commandes saisies par l'utilisateur, tandis que les autres correspondent aux sorties du terminal.
Il m'arrive également d'ajouter des commentaires en fin de ligne à l'aide de # ….

Origine de cette convention ?

J'ai cherché à retracer l'origine de cette pratique et elle semble très ancienne, probablement adoptée dès les débuts d'Unix en 1971.
On retrouve cette syntaxe notamment dans le livre The Unix Programming Environment (pdf), publié en 1984.

Ne pas inclure de $ si un bloc ne contient aucune sortie de commande

La règle MD014 de Markdownlint aborde ce sujet :

MD014 - Dollar signs used before commands without showing output

Tags: code

Aliases: commands-show-output

This rule is triggered when there are code blocks showing shell commands to be typed, and the shell commands are preceded by dollar signs ($):

$ ls
$ cat foo
$ less bar

The dollar signs are unnecessary in the above situation, and should not be included:

ls
cat foo
less bar

However, an exception is made when there is a need to distinguish between typed commands and command output, as in the following example:

$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz

Rationale: it is easier to copy and paste and less noisy if the dollar signs are omitted when they are not needed. See https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code for more information.

source

Pendant un certain temps, j’ai suivi la recommandation de ne pas inclure de $ dans un bloc de commande lorsqu’il n’affiche aucune sortie.

Après quelques années, j’ai décidé de ne plus appliquer cette règle pour la raison suivante :

  • Lorsque la documentation mélange des fichiers de configuration et des commandes sans $, j’ai du mal à distinguer ce qui doit être exécuté dans un terminal et ce qui relève de la configuration.

Pour éviter toute ambiguïté, j’ai adopté une approche radicale : toujours utiliser $ pour indiquer une commande à exécuter, même si le bloc ne contient pas de sortie.

Je n'aime pas les $ dans les blocs de commande, car que je ne peux pas copier / coller facilement !

Je comprends tout à fait cette remarque. Cependant, ces "screenshots" de session de terminal n'ont pas vocation à être copiées / collées en masse.
Ils ont avant tout une fonction explicative.
Ce sont des sortes de "screenshot".

Si j'éprouve le besoin de faire souvent des "copier / coller" d'exemples de session terminal, alors je considère que c'est le signe qu'un script "helper" serait plus approprié pour exécuter ce groupe de commandes d’un seul coup.

Par exemple, je peux remplacer ce contenu :

Ensure that the following prerequisites have been installed: mise and direnv, see instruction in ../README.md.

$ mise trust
$ mise install
$ scw version
Version    2.34.0

Par celui-ci (qui indique l'existence du script ./scripts/mise-install.sh) :

Ensure that the following prerequisites have been installed: mise and direnv, see instruction in ../README.md (or execute ./scripts/mise-install.sh).

$ mise trust
$ mise install
$ scw version
Version    2.34.0

Cela évite les copier-coller répétitifs tout en conservant la clarté de l’explication.

Journal du mercredi 29 janvier 2025 à 16:29 #OnMaPartagé, #JaiDécouvert, #gitlab, #markdown

Alexandre m'a fait remarquer que GitLab a activé par défaut une extension Markdown de génération automatique de TOC :

A table of contents is an unordered list that links to subheadings in the document. You can add a table of contents to issues, merge requests, and epics, but you can’t add one to notes or comments.

Add one of these tags on their own line to the description field of any of the supported content types:

[[_TOC_]]
or
[TOC]
  • Markdown files.
  • Wiki pages.
  • Issues.
  • Merge requests.
  • Epics.

source

Je trouve cela excellent que cette extension Markdown soit supportée un peu partout, en particulier les issues, Merge Request… 👍️.

Cette fonctionnalité a été ajoutée en mars 2020 🫢 ! Comment j'ai pu passer à côté ?

GitHub permet d'afficher un TOC au niveau des README, mais je viens de vérifier, GitHub ne semble pas supporter cette extension TOC Markdown au niveau des issues… Pull Request…

Journal du mercredi 11 décembre 2024 à 11:22 #markdown, #markup, #JaiDécouvert

#JaiDécouvert ArchieML (https://archieml.org/) qui est un markup language créé en 2015 par Michael Strickland qui travaille chez The New York Times.

Mon premier sentiment a été « pourquoi ne pas utiliser du Markdown ».

Ensuite, en lisant la documentation, j'ai compris que ce markup language était utilisé pour renseigner des valeurs dans différents champs. Comme le dit la documentation, ArchieML est une alternative à JSON ou YAML.

En explorant la section « Why not YAML? Or JSON? », j'ai compris la philosophie fondamentale d'ArchieML : offrir un langage de balisage qui soit particulièrement tolérant aux erreurs de syntaxe, notamment concernant l'indentation.
Cette approche répond spécifiquement aux besoins des journalistes qui, contrairement aux développeurs, ne sont généralement pas familiers avec les conventions strictes d'indentation que l'on trouve dans d'autres langages de balisage.

Ensuite, je me suis demandé : « Pourquoi ne pas demander aux journalistes de saisir leur article dans une page d'édition web, qui présente différents champs bien distincts ? ».

Je pense que la réponse se trouve ici :

And finally, because we make extensive use of Google Documents's concurrent-editing features…

source

Tout comme j'aime travailler avec des documents "plain text", peut-être que les journalistes préfèrent finalement travailler sur de simples documents textes plutôt qu'une page web d'édition, pour des raisons de rapidité d'utilisation : copier-coller rapide, fonctionnalité de commentaire collaboratif de Google Docs…

Je découvre dans la section ressources différentes librairies d'intégration à Google Docs.

Je découvre aussi que ArchieML est utilisé par d'autres journaux :

  • Quartz
  • The Atlanta Journal-Constitution
  • Fusion
  • The Wall Street Journal

Au final, je n'ai pas d'opinion définitive au sujet de cette méthode d'édition d'article 🤔.

Journal du lundi 18 novembre 2024 à 09:44 #MachineLearning, #UnJourPeuxÊtre

Un ami me demande des ressources pour se former au Machine Learning.

Je ne suis pas expert dans ce domaine.

Lorsque je me forme sur un sujet, j’aime commencer par comprendre le contexte global, son histoire et alterner entre l’acquisition de connaissances théoriques et pratiques.

Pour me former sérieusement, j'envisage un jour de prendre le temps de :

Je n'ai pas classé l'ordre d'étude des séries avec rigueur, cet ordre est sans doute à modifier.

Pour chaque élément, j'ai précisé entre parenthèses une estimation optimiste du temps nécessaire à l'écoute ou à la lecture.

D'après cette liste, j'estime à environ 86 heures pour me former sur ce sujet, soit l'équivalent de 15 jours à temps plein ou presque un mois complet.

Ensuite, j'ai quelques idées de projets de mise en pratique :

  • Développer une extension pour navigateur qui, lors de la rédaction d’un e-mail depuis Fastmail, transforme automatiquement le contenu du message en HTML en texte brut au format Markdown.
    • Ajouter ensuite une fonctionnalité pour supprimer automatiquement les signatures.
  • Concevoir un outil capable de découper une vidéo de Tennis de Table en segments correspondant à chaque point joué.

Journal du lundi 26 août 2024 à 22:10 #collaboration, #BonnePratique, #communication, #markdown

Lorsque vous collaborez avec moi et partagez du code source ou des extraits de terminal dans un logiciel compatible avec le format Markdown, tel que GitHub, GitLab, Mattermost, Zulip, etc., je vous encourage à entourer vos extraits avec des balises ```. Par exemple :

De même, pour les citations de texte en prose, utilisez les caractères > au début de chaque ligne, comme illustré ci-dessous :

> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse justo neque, facilisis ut commodo in, auctor at tellus. Morbi non mattis risus. In vehicula risus felis, ac ullamcorper magna consequat et.
> Sed finibus, lorem a rutrum pulvinar, magna urna rutrum tortor, eget faucibus dolor enim sit amet lacus. Nulla pulvinar ligula eu leo rhoncus faucibus.

Ce qui produira :

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse justo neque, facilisis ut commodo in, auctor at tellus. Morbi non mattis risus. In vehicula risus felis, ac ullamcorper magna consequat et. Sed finibus, lorem a rutrum pulvinar, magna urna rutrum tortor, eget faucibus dolor enim sit amet lacus. Nulla pulvinar ligula eu leo rhoncus faucibus.

Ces deux recommandations permettent d'améliorer le confort de lecture de vos messages.

Voir aussi je préfère recevoir les extraits de vos textes au format texte plutôt que sous forme de captures d'écran.

Journal du lundi 05 août 2024 à 14:58 #markdown

Le projet SilverBullet.mb utilise le terme Transclusion : https://silverbullet.md/Transclusions

Transclusions are an extension of the Markdown syntax enabling inline embedding of content.

The general syntax is ![[path]].

Journal du mercredi 31 juillet 2024 à 17:33 #markdown, #obsidian, #JeMeDemande

#JeMeDemande comment définir la largeur d'une image dans Obsidian.

J'ai commencé par faire une recheche sur le forum d'Obsidian : image size.

Et j'ai trouvé ma réponse. La syntax Markdown suivante fonctionne :

![400](20240731165227.png)

🙂