Plugin Discourse vers Markdown

Personnalisation Greffon
,
1

discourse-to-markdown est un nouveau plugin qui renvoie le contenu du forum au format Markdown lorsque le client envoie Accept: text/markdown ou ajoute .md à la fin de n’importe quelle URL de contenu.

Nous l’utilisons sur notre propre forum à l’adresse https://discourse.roots.io :

curl -H "Accept: text/markdown" https://discourse.roots.io/latest
curl https://discourse.roots.io/t/serve-your-wordpress-posts-as-markdown/30321.md

Le HTML est coûteux à fournir à un LLM, et servir du Markdown ne contenant que le contenu réduit souvent l’utilisation des tokens de 3 à 5 fois. Cela signifie des appels API moins chers, des réponses plus rapides et plus de place dans la fenêtre de contexte pour que le modèle puisse raisonner. Consultez https://acceptmarkdown.com pour une présentation plus détaillée et une vérification de compatibilité pour n’importe quel site.

Comment les clients demandent du Markdown

Trois points d’entrée :

  1. En-tête Accept: text/markdown (idéal pour les LLM)
  2. Suffixe d’URL .md
  3. Découverte (chaque réponse HTML annonce son équivalent Markdown via Link: <...>; rel="alternate"; type="text/markdown" et une balise <link rel="alternate"> dans <head>, les flux RSS contiennent un <atom:link> pointant vers l’équivalent Markdown)

Routes prises en charge

Route HTML Markdown
Sujet /t/:slug/:id /t/:slug/:id.md
Post unique /t/:slug/:id/:post_number /t/:slug/:id/:post_number.md
Catégorie /c/:slug/:id /c/:slug/:id.md
Balise /tag/:tag /tag/:tag.md
Derniers /latest /latest.md
Top /top /top.md
Populaires /hot /hot.md
Activité utilisateur /u/:username/activity /u/:username/activity.md

Installation

Ajoutez le plugin à votre fichier app.yml :

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/roots/discourse-to-markdown.git

Reconstruisez le conteneur :

cd /var/discourse
./launcher rebuild app

Ensuite, activez-le dans Admin → Paramètres → Plugins → Sortie Markdown.

Notes sur la conversion

Le plugin convertit le HTML cooked de Discourse — la représentation rendue que les lecteurs voient, avec les oneboxes développées, les mentions liées et les citations attribuées — et non le raw. Cela préserve ce que les lecteurs voient réellement et rend le résultat portable sur n’importe quel rendu compatible GFM. Les éléments spécifiques à Discourse (citations, oneboxes, détails, mentions, hashtags, emojis, lightboxes, sondages) sont réécrits de manière cohérente avant la conversion.

Le Markdown converti est mis en cache dans Redis par post, en utilisant une clé basée sur post.id + post.updated_at, et les modifications invalident automatiquement le cache.

Paramètres

Paramètre Valeur par défaut Objectif
discourse_to_markdown_enabled false Interrupteur principal pour le plugin
discourse_to_markdown_md_urls_enabled true Accepter les suffixes d’URL .md comme équivalent de la route HTML
discourse_to_markdown_strict_accept false Retourner 406 Not Acceptable lorsque l’en-tête Accept du client exclut à la fois text/html et text/markdown
discourse_to_markdown_emit_vary true Émettre Vary: Accept sur les réponses Markdown et 406 pour éviter que les caches ne servent des représentations croisées
discourse_to_markdown_include_post_metadata true Inclure l’URL, la catégorie, les balises, l’auteur et les horodatages dans la représentation Markdown

Ressources

9 « J'aime »
2

C’est super, merci de l’avoir publié !

C’est également une approche assez géniale. Elle produit un Markdown plus riche que la sortie brute, car elle bénéficie de l’infrastructure de « cuisson » de Discourse.

2 « J'aime »
5

OMG, c’est exactement ce que je cherchais, quelle synchronisation parfaite ! Nous utilisons l’API ou MCP fréquemment et cela nous a toujours énervés que le contenu brut ne contienne pas les URL d’images résolues.

Merci pour votre travail !

Edit : Est-ce que cela pourrait d’une manière ou d’une autre être utilisé avec Discourse MCP aussi ?

1 « J'aime »
6

Ravi que cela soit utile !

Discourse MCP pourrait ajouter la négociation de contenu comme option. Cela ne nécessiterait pas l’installation de ce plugin ; il pourrait demander Accept: text/markdown à l’URL canonique du sujet ou du message et revenir au comportement actuel de l’API JSON si le site ne prend pas en charge Markdown.

Ce plugin n’est qu’une des façons pour un site Discourse de répondre à cette demande aujourd’hui. Sans ce plugin ou une prise en charge équivalente dans le cœur de Discourse, l’en-tête Accept seul ne modifierait pas la sortie de l’API JSON.

L’intégration idéale pour MCP pourrait donc être : essayer text/markdown sur l’URL du contenu en premier, puis revenir à /t/:id.json?include_raw=true.

1 « J'aime »
7

C’est drôle que tu dises cela, car Claude l’a résolu exactement de cette manière…