Ajouter des articles de blog
Objectif
Ajouter le contenu de l'utilisateur à un blog statique existant sans imposer un nouveau système de blog.
Cette compétence doit d'abord comprendre comment le site actuel représente déjà les articles, puis ajouter du nouveau contenu dans ce style. Ce n'est pas un convertisseur Markdown vers HTML générique.
Contrat
Entrées :
- Dossier du site statique existant et son système d'article/index/modèle actuel.
- Un ou plusieurs articles sources : Markdown, notes Obsidian, documents Word, ancien HTML, texte collé, images, pièces jointes ou dossiers de contenu.
- Métadonnées optionnelles telles que le titre, la date, les tags, le résumé, le slug, l'image de couverture et la portée de l'importation.
Sorties :
- Nouvelles pages d'article/détail qui correspondent au style d'article existant du site.
- Points d'entrée mis à jour tels que l'index du blog, les archives, les tags/catégories, les articles récents de la page d'accueil, les données de recherche, le flux RSS ou le sitemap lorsque ces systèmes existent déjà.
- Images et pièces jointes locales copiées/reliées avec des chemins relatifs aux pages.
- Instructions de publication
EDITING.mdmises à jour le cas échéant.
Limites :
- Ne pas reconcevoir le site ni créer un nouveau système d'article lorsqu'un système existant est clair.
- Ne pas inventer de métadonnées, de dates, d'auteurs ou d'affirmations que la source ne supporte pas.
- Ne pas ajouter silencieusement des dépendances mathématiques/CDN distantes.
- Ne pas publier ; utiliser
publish-static-site.
Condition de succès :
- Les nouveaux articles sont rendus dans le style existant et sont accessibles depuis les index appropriés.
- Les images, les mathématiques, les liens, le code, les tableaux et le contenu enrichi fonctionnent ou les éléments non résolus sont explicitement signalés.
- Les chemins sont relatifs aux pages depuis les pages d'article et d'index.
- Les pages concernées passent la validation du navigateur et
review-static-sitepeut réussir ou ne signaler que des limitations acceptées.
Si la condition échoue :
- Corriger la conversion, les métadonnées, les chemins, les ressources ou le câblage d'index dans cette compétence.
- Utiliser
edit-site-partpour les petites corrections visuelles causées par l'importation. - Utiliser à nouveau
review-static-siteaprès les corrections.
Quand l'utiliser
Utilisez cette compétence lorsque l'utilisateur souhaite :
- Ajouter un nouvel article, une note, un essai ou un article de blog.
- Importer plusieurs fichiers Markdown dans un site statique.
- Déplacer des articles d'un ancien blog vers un nouveau site généré.
- Convertir le texte d'un article collé en une page d'article du site.
- Mettre à jour l'index du blog, les archives, les tags, les articles récents de la page d'accueil ou les points d'entrée associés.
- Préserver le langage visuel actuel du site tout en ajoutant du contenu.
N'utilisez pas cette compétence pour choisir un thème, construire un nouveau site à partir de zéro, recréer le style d'un site web, personnaliser le contenu du profil/"À propos", effectuer une petite modification visuelle, publier le site ou convertir le projet vers un framework.
Entrées
Utilisez ce qui est disponible :
- Dossier du site statique, généralement
site/,dist/,out/oupublic/. - Un ou plusieurs fichiers Markdown, documents Word, articles collés, anciens fichiers HTML, dossiers d'images ou dossiers de contenu.
EDITING.md, plan de page ou notes de transfert des compétences précédentes.- Pages de modèles d'articles existants ou articles représentatifs.
- Titre, date, tags, catégorie, résumé, slug, image de couverture et préférence de publication fournis par l'utilisateur.
- S'il faut importer tous les articles, un sous-ensemble sélectionné ou d'abord un lot représentatif.
Si le contenu source est volumineux, inspectez d'abord la structure et évitez d'importer tout à l'aveugle.
1. Comprendre le système d'article existant
Avant d'écrire de nouveaux articles, inspectez le fonctionnement actuel du site.
Vérifiez :
- Les fichiers d'article tels que
posts/*.html,notes/*.html,articles/*.htmlou les dossiers de route imbriqués. - Les pages d'index telles que
blog.html,archive/index.html,notes/index.html,tags/index.htmloucategory/index.html. - Les fichiers de données tels que
data/posts.json,data/notes.json,data/site.jsonouprofile.json. - Les tableaux de données JavaScript dans
assets/script.jsou des fichiers similaires. - Les sections de la page d'accueil pour les articles récents, les articles en vedette, les notes, les listes de lecture ou les points forts d'écriture.
- Les pages d'article/détail existantes qui peuvent être utilisées comme modèles.
- La stratégie de chemin existante : si les modèles utilisent des liens relatifs aux pages tels que
../assets/style.cssou des liens racine du serveur tels que/assets/style.css. - RSS, Atom, sitemap, index de recherche ou pages de tags/catégories s'ils sont déjà présents.
- Les instructions
EDITING.mdpour ajouter des articles. - Les conventions d'images et de pièces jointes existantes, telles que
assets/images/posts/, dossiers d'articles colocalisés, champs de couverture, classes de figures, balisage de lightbox, légendes ou wrappers d'images responsives. - Les conventions de contenu enrichi existantes, telles que le rendu mathématique, la coloration syntaxique du code, les tableaux, les notes de bas de page, les callouts, les ancres de titre, la table des matières, les cartes de liens, les intégrations, les diagrammes et les sections de citation/référence.
Suivez la structure existante. N'inventez pas un nouveau système d'article lorsque le site en a déjà un.
2. Extraire les métadonnées de l'article
Pour chaque article source, extrayez ou déduisez :
- Titre.
- Date.
- Slug.
- Tags ou catégorie.
- Résumé ou extrait.
- Image de couverture ou image à la une, si présente et utilisable.
- Chemin source.
- Temps de lecture, uniquement si le site actuel l'utilise déjà ou s'il est facile à calculer de manière cohérente.
Utilisez le frontmatter lorsqu'il est présent. Sinon, déduisez-le du premier titre, du nom de fichier, du dossier environnant, du texte de date visible ou du premier paragraphe.
N'inventez pas de dates, tags, auteurs ou affirmations spécifiques. Si un champ est manquant et ne peut être déduit, utilisez un espace réservé clair ou omettez le champ lorsque le style du site le permet.
3. Convertir le contenu au style du site
Créez de nouvelles pages d'article en faisant correspondre le modèle d'article existant et l'expérience de lecture.
Préservez :
- L'en-tête, la navigation, le pied de page, les barres latérales et l'enveloppe partagée.
- La typographie de l'article, l'espacement, la disposition des métadonnées, les tags, les liens de retour et les liens connexes.
- Tout langage de thème spécial, tel que les entrées de journal, les notes de terrain, les fiches, le cadre terminal/archive ou les essais minimalistes.
- Les conventions de classes CSS existantes et les structures de données.
Pour Markdown :
- Convertissez les titres, les paragraphes, les citations en bloc, les listes, les listes de tâches, les tableaux, les blocs de code, les liens, les notes de bas de page, les callouts et les images en HTML sémantique.
- Préservez les étiquettes de langue de code lorsqu'elles sont disponibles.
- Gardez les références d'images relatives aux pages et ne copiez les images locales que si nécessaire.
- Conservez le texte chinois, japonais, coréen, latin accentué et autre texte non ASCII sous forme de UTF-8 lisible.
Pour l'ancien HTML :
- Extrayez le corps de l'article et les métadonnées.
- Supprimez l'ancien chrome du site, les analyses, les commentaires, la navigation non liée et l'identité du site source.
- Ré-enveloppez le contenu dans le modèle d'article du nouveau site.
3.5. Préserver la compatibilité des chemins statiques
Lors de l'ajout d'articles, calculez les chemins à partir de l'emplacement de chaque page générée. Ne copiez pas aveuglément les chemins de index.html dans les pages d'article imbriquées.
Règles par défaut :
- Les nouvelles pages d'article doivent utiliser des liens relatifs aux pages pour le CSS partagé, JavaScript, les polices, les images et la navigation.
- Si l'article est généré à
posts/my-post.html, les ressources partagées ont généralement besoin de../assets/style.css,../assets/script.jset des images d'article telles que../assets/images/posts/my-post/figure.png. - Les liens depuis les pages racines vers l'article doivent généralement être
posts/my-post.html. - Les liens depuis l'article vers les pages racines doivent généralement être
../index.html,../blog.htmlou../archive/index.html, selon la structure. - N'introduisez pas de chemins absolus racine tels que
/assets/...,/posts/...,/data/...ou/images/...sauf si le site existant les utilise intentionnellement et que l'utilisateur accepte que l'ouverture directe defile://et l'hébergement sur un sous-chemin puissent être rompus. - Mettez à jour les liens générés par JavaScript, les résultats de recherche, les filtres de tags, les liens d'articles connexes, les chemins de couverture, les entrées RSS/sitemap et tous les fichiers de données avec la même stratégie de chemin.
- Si le site existant a déjà des liens absolus racine par accident, signalez-le et préférez corriger les chemins affectés plutôt que d'étendre le problème.
Évitez les problèmes de récupération de fichier local :
- Ne faites pas dépendre les articles nouvellement ajoutés de
fetch()sur du JSON/Markdown local pour le corps de l'article. - Si les index sont rendus à partir de données, gardez les liens d'article essentiels visibles en HTML ou utilisez un objet de données JavaScript relatif qui fonctionne avec un aperçu en ouverture directe.
4. Gérer les formats de contenu enrichi
Préservez intentionnellement le contenu enrichi au lieu de tout aplatir en paragraphes simples.
Inspectez d'abord si le site actuel prend déjà en charge :
- Le rendu mathématique avec KaTeX, MathJax, CSS personnalisé ou blocs TeX bruts.
- La coloration syntaxique du code, les étiquettes de langue, les boutons de copie ou les cadres de code de style terminal.
- Les tableaux, les wrappers de tableaux responsifs, les notes de bas de page, les callouts, les admonitions, les citations et les listes de tâches.
- Les ancres de titre, la table des matières, les backlinks, les notes connexes ou les liens de section.
- Les cartes de liens, les listes de signets, les pages d'index d'URL, les citations, les listes de références ou les sections de bibliographie.
- Les médias intégrés tels que la vidéo, l'audio, les PDF, les iframes, les diagrammes Mermaid, les diagrammes Excalidraw/SVG ou les pièces jointes téléchargeables.
Suivez le modèle existant lorsqu'il existe. Si aucun modèle n'existe, utilisez du HTML sémantique simple et signalez toute fonctionnalité nécessitant un moteur de rendu supplémentaire.
Mathématiques et formules :
- Préservez les mathématiques en ligne et en affichage de
$...$,$$...$$,\(...\),\[...\]ou les exportations d'équations Word. - Utilisez le moteur de rendu mathématique existant du site s'il est présent.
- Si la source contient de nombreuses formules et qu'aucun moteur de rendu n'existe, préférez une intégration KaTeX locale pour les sites statiques simples : stockez le CSS/JS/polices KaTeX dans un dossier vendor local, ajoutez un petit script de rendu local et ne vous fiez pas à un CDN.
- N'ajoutez pas silencieusement une dépendance MathJax/KaTeX distante à un site autrement sans dépendance.
- Préservez le TeX original à l'intérieur des éléments marqués comme mathématiques comme solution de repli, puis rendez-le dans le navigateur. Si le rendu échoue pour une formule, la solution de repli TeX lisible doit rester visible au lieu de casser la page.
- Normalisez la syntaxe source évidente dont KaTeX a besoin, comme les flèches softmax,
\cdot,\times, la ponctuation accidentellement mélangée aux formules et les expressions Q/K/V courantes. - Ne laissez pas les articles lourds en formules sous forme de boîtes TeX ressemblant à du code lorsqu'un moteur de rendu mathématique a été ajouté.
- Gardez les formules lisibles dans la source et dans la solution de repli du navigateur.
Blocs de code :
- Préservez les noms de langue de code délimités.
- Échappez le HTML à l'intérieur des blocs de code.
- Gardez les longues lignes de code défilables plutôt que de casser la mise en page.
- Réutilisez le style de bloc de code existant, les boutons de copie et les conventions de coloration syntaxique.
- N'exécutez pas le code source des articles.
Tableaux :
- Convertissez les tableaux Markdown, Word ou HTML en tableaux sémantiques.
- Enveloppez les tableaux larges dans le conteneur de tableau responsive existant du site ou ajoutez un petit wrapper local.
- Préservez les lignes d'en-tête, l'intention d'alignement et les légendes lorsqu'elles sont disponibles.
Liens, index d'URL et références internes :
- Préservez les liens externes avec un texte de lien clair.
- Convertissez les liens relatifs et les liens
.mdde Markdown vers le chemin HTML statique généré lorsque l'article cible est importé. - Convertissez les wikilinks Obsidian tels que
[[Note]],[[Note#Heading]]et[[Note|Alias]]en liens normaux lorsque la cible peut être résolue. - Préservez les liens internes non résolus comme des espaces réservés visibles ou du texte brut, et signalez-les.
- Générez des ID d'ancre stables lorsque le site utilise des liens d'ancrage ou une table des matières.
- Pour les articles d'index d'URL, de signets ou de tour d'horizon de liens, conservez la structure de la liste. Utilisez le style de carte de lien/liste existant du site lorsqu'il est présent ; n'inventez pas de cartes d'aperçu qui nécessitent la récupération de métadonnées distantes à moins que l'utilisateur ne le demande.
Notes de bas de page, citations et références :
- Convertissez les notes de bas de page Markdown en une section de notes de bas de page en utilisant le style existant du site s'il est présent.
- Préservez les étiquettes de citation, les entrées de bibliographie et les liens de référence.
- Si le texte source utilise des clés de citation non résolues telles que
[@paper2024], gardez-les visibles et signalez que les métadonnées de citation sont manquantes à moins qu'un fichier de bibliographie ne soit fourni.
Callouts, admonitions et types de blocs :
- Convertissez les callouts de style Obsidian/GitHub tels que
> [!NOTE],> [!TIP],> [!WARNING]et> [!IMPORTANT]dans le modèle de callout/carte/citation le plus proche du site. - Préservez les listes de tâches sous forme de listes de contrôle lorsque le site actuel propose un style de liste de contrôle ; sinon, utilisez le balisage de case à cocher désactivée ou des listes simples.
Intégrations et pièces jointes :
- Pour les PDF, diapositives, jeux de données, téléchargements, audio et vidéo, préférez un lien clair ou une carte de téléchargement sauf si le site intègre déjà ce type de média.
- Ne copiez les pièces jointes locales que lorsqu'elles sont fournies par l'utilisateur.
- Conservez les intégrations distantes uniquement lorsque l'utilisateur les possède ou les référence intentionnellement.
- Pour les blocs Mermaid ou diagrammes, utilisez le moteur de rendu existant s'il est présent. Si aucun moteur de rendu n'existe, préservez le bloc source et signalez-le, ou convertissez-le en SVG/PNG statique uniquement lorsque c'est pratique et approprié.
5. Gérer les images et les ressources de l'article
Gérez les images conformément aux conventions de ressources actuelles du site.
Inspectez d'abord comment les articles existants stockent et rendent les images :
- Dossier de ressources partagé tel que
assets/images/posts/<slug>/. - Ressources d'article colocalisées telles que
posts/<slug>/images/. - Champs de données tels que
cover,heroImage,thumbnailouimages. - Balisage de figure, légendes, liens de lightbox, chargement différé, attributs de largeur/hauteur et classes CSS responsives.
Préférez le modèle existant. Si aucun modèle n'existe, utilisez une convention statique simple telle que :
assets/images/posts/<post-slug>/
Pour les sources Markdown :
- Résolvez les liens d'images relatifs à partir du dossier du fichier Markdown.
- Copiez les images locales dans le dossier d'images d'article du site si nécessaire.
- Réécrivez les références d'images Markdown vers les nouveaux chemins de site relatifs.
- Pour les pages d'article imbriquées, incluez la profondeur
../correcte dans les chemins d'images. - Préservez le texte alternatif de Markdown lorsqu'il est présent.
- Convertissez les légendes d'images si la source utilise du texte en italique à proximité, des attributs de titre ou des intégrations de style Obsidian.
- Ne laissez pas de liens pointant vers des chemins de disque locaux absolus.
Pour les notes Obsidian :
- Prenez en charge les intégrations courantes telles que
![[image.png]]et les dossiers de pièces jointes relatifs. - Recherchez les dossiers de pièces jointes probables près de la note, tels que
attachments/,assets/,images/ou le dossier de pièces jointes configuré du coffre lorsqu'il est visible. - Réécrivez les intégrations en balisage HTML d'image ou de figure normal.
Pour les sources Word .docx :
- Extrayez les images intégrées du package du document ou utilisez les outils de document disponibles.
- Préservez l'ordre des images par rapport au texte environnant lorsque c'est possible.
- Enregistrez les images extraites dans le dossier d'images d'article avec des noms stables.
- Utilisez les légendes ou le texte alternatif à proximité lorsqu'ils sont disponibles.