J'écris un readme pour mon projet github au format .md. Existe-t-il un moyen de tester à quoi ressemblera mon fichier readme.md avant de valider github?

Plusieurs façons: Si vous êtes sur un Mac, utilisez Mou .

Si vous voulez tester dans un navigateur, vous pouvez essayer StackEdit , comme indiqué par @Aaron ou Dillinger, car Notepag semble être en panne maintenant. Personnellement, j'utilise Dillinger car il fonctionne et enregistre tous mes documents dans la base de données locale de mon navigateur.

Atom fonctionne bien hors de la boîte - ouvrez simplement le fichier Markdown et appuyez sur Ctrl + Shift + M pour basculer le panneau d'aperçu Markdown à côté de lui. Il gère également le HTML et les images.

Celui-ci s'est révélé fiable depuis un certain temps: http://tmpvar.com/markdown.html

C'est une question assez ancienne, cependant, puisque je suis tombée dessus lors d'une recherche sur Internet, ma réponse est peut-être utile aux autres. Je viens de trouver un outil CLI très utile pour rendre le démarquage aromatisé GitHub: grip . Il utilise l'API de GitHub, rend donc assez bien.

Franchement, le développeur de grip , a une réponse plus élaborée à ces questions très similaires:

• Existe-t-il un utilitaire de ligne de commande pour le rendu de démarque aromatisée github?
• Quelle est la meilleure façon de modifier le fichier Readme.md de GitHub?

Je le modifie généralement sur le site Web de GitHub directement et je clique sur "Aperçu" juste au-dessus de la fenêtre de modification.

C'est peut-être une nouvelle fonctionnalité qui a été ajoutée depuis la publication de ce message.

Visual Studio Code a la possibilité de modifier et de prévisualiser les modifications du fichier md. Étant donné que VS Code est indépendant de la plate-forme, cela fonctionnerait pour Windows, Mac et Linux.

Pour basculer entre les vues, appuyez sur Ctrl + Maj + V dans l'éditeur. Vous pouvez afficher l'aperçu côte à côte (Ctrl + KV) avec le fichier que vous modifiez et voir les modifications reflétées en temps réel lors de la modification.

Aussi...

Q: VS Code prend-il en charge la réduction de saveur GitHub?

R: Non, VS Code cible la spécification CommonMark Markdown à l'aide de la bibliothèque markdown-it. GitHub se dirige vers la spécification CommonMark.

Plus de détails ici

Sur le Web, utilisez Dillinger . C'est génial.

J'utilise un fichier HTML hébergé localement pour prévisualiser les fichiers Lisezmoi de GitHub.

J'ai examiné plusieurs options existantes, mais j'ai décidé de lancer la mienne pour répondre aux exigences suivantes:

• Un seul fichier
• URL hébergée localement (intranet)
• Aucune extension de navigateur requise
• Pas de traitement côté serveur hébergé localement (par exemple, pas de PHP)
• Léger (par exemple, pas de jQuery)
• Haute fidélité: utilisez GitHub pour rendre le Markdown et le même CSS

Je garde des copies locales de mes dépôts GitHub dans des répertoires frères sous un répertoire "github".

Chaque répertoire repo contient un fichier README.md:

.../github/
           repo-a/
                  README.md
           repo-b/
                  README.md
           etc.

Le répertoire github contient le fichier HTML "prévisualisation":

.../github/
           readme.html

Pour prévisualiser un fichier Lisezmoi, je parcours github / readme.html, en spécifiant le référentiel dans la chaîne de requête:

http://localhost/github/readme.html?repo-a

Vous pouvez également copier le fichier readme.html dans le même répertoire que le fichier README.md et omettre la chaîne de requête:

http://localhost/github/repo-a/readme.html

Si le fichier readme.html se trouve dans le même répertoire que README.md, vous n'avez même pas besoin de servir readme.html sur HTTP: vous pouvez simplement l'ouvrir directement à partir de votre système de fichiers.

Le fichier HTML utilise l' API GitHub pour rendre le Markdown dans un fichier README.md. Il y a une limite de taux : au moment de la rédaction, 60 demandes par heure .

Fonctionne pour moi dans les versions de production actuelles de Chrome, IE et Firefox sur Windows 7.

La source

Voici le fichier HTML (readme.html):

<!DOCTYPE html>
<!--
     Preview a GitHub README.md.

     Either:

     -  Copy this file to a directory that contains repo directories,
        and then specify a repo name in the query string.

        For example:

          http://localhost/github/readme.html?myrepo

     or

     -  Copy this file to the directory that contains a README.md,
        and then browse to this file without specifying a query string.

        For example:

          http://localhost/github/myrepo/readme.html

        (or just open this file in your browser directly from
        your file system, without HTTP)
-->
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta name="author" content="Graham Hannington"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GitHub readme preview</title>
<link rel="stylesheet" type="text/css" href="http://primercss.io/docs.css"/>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";

var readmeURL;

var queryString = location.search.substring(1);

if (queryString.length > 0) {
  readmeURL = queryString + "/" + README_FILE_NAME;
} else {
  readmeURL = README_FILE_NAME;
}

// Get Markdown, then render it as HTML
function getThenRenderMarkdown(markdownURL) {
  var xhr = new XMLHttpRequest();
  xhr.open("GET", markdownURL, true);
  xhr.responseType = "text";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
     // Response text contains Markdown
      renderMarkdown(this.responseText);
    }
  }
  xhr.send();
}

// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
  xhr.responseType = "html";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
      document.getElementById("readme").innerHTML = this.response;
    }
  }
  xhr.send(markdown);
}

window.onload = function() {
  getThenRenderMarkdown(readmeURL);
}
//]]>
</script>
</head>
<body>
<header class="masthead">
<div class="container">
<span class="masthead-logo"><span class="mega-octicon
octicon-mark-github"></span>GitHub readme preview</span>
</div>
</header>
<div class="container">
<div id="readme" class="markdown-body">
<p>Rendering markdown, please wait...</p>
</div>
<footer class="footer">Rendering by
<a href="https://developer.github.com/v3/markdown/">GitHub</a>,
styling by <a href="http://primercss.io/">Primer</a>.</footer>
</div>
</body>
</html>

Notes aux développeurs

• En général, j'emballe mon code dans un IIFE, mais dans ce cas, je n'ai pas vu le besoin, et j'ai pensé que je resterais concis
• Je n'ai pas pris la peine de prendre en charge IE de niveau supérieur
• Par souci de concision, j'ai omis le code de gestion des erreurs (me croyez-vous?!)
• Je serais ravi des conseils de programmation JavaScript

Des idées

• J'envisage de créer un référentiel GitHub pour ce fichier HTML et de placer le fichier dans la branche gh-pages, afin que GitHub le serve de page Web "normale". Je modifierais le fichier pour accepter une URL complète - du fichier README (ou de tout autre fichier Markdown) - comme chaîne de requête. Je suis curieux de voir si être hébergé par GitHub contournerait la limite de demande d'API GitHub, et si j'exécute des problèmes inter-domaines (en utilisant une demande Ajax pour obtenir le Markdown à partir d'un domaine différent de celui qui sert la page HTML) .

Version originale (obsolète)

J'ai conservé cet enregistrement de la version originale pour une valeur de curiosité. Cette version avait les problèmes suivants qui sont résolus dans la version actuelle:

• Il a fallu télécharger certains fichiers associés
• Il ne supportait pas d'être déposé dans le même répertoire que le fichier README.md
• Son HTML était plus fragile; plus sensible aux changements dans GitHub

Le répertoire github contient le fichier HTML "prévisualisation" et les fichiers associés:

.../github/
           readme-preview.html
           github.css
           github2.css
           octicons.eot
           octicons.svg
           octicons.woff

J'ai téléchargé les fichiers de police CSS et octicons depuis GitHub:

https://assets-cdn.github.com/assets/github- ... .css
https://assets-cdn.github.com/assets/github2- ... .css
https://github.com/static/fonts/octicons/octicons.* (eot, woff, svg)

J'ai renommé les fichiers CSS pour omettre la longue chaîne de chiffres hexadécimaux dans les noms d'origine.

J'ai édité github.css pour faire référence aux copies locales des fichiers de police octicons.

J'ai examiné le code HTML d'une page GitHub et j'ai reproduit suffisamment la structure HTML entourant le contenu du fichier Lisezmoi pour fournir une fidélité raisonnable; par exemple, la largeur contrainte.

Le CSS GitHub, la police octicons et le "conteneur" HTML pour le contenu du fichier Lisezmoi sont des cibles mobiles: je devrai télécharger périodiquement de nouvelles versions.

J'ai joué avec l'utilisation de CSS de divers projets GitHub. Par exemple:

<link rel="stylesheet" type="text/css"
      href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">

mais a finalement décidé d'utiliser le CSS de GitHub lui-même.

La source

Voici le fichier HTML (readme-preview.html):

<!DOCTYPE html>
<!-- Preview a GitHub README.md.
     Copy this file to a directory that contains repo directories.
     Specify a repo name in the query string. For example:

     http://localhost/github/readme-preview.html?myrepo
-->
<html>
<head>
<title>Preview GitHub readme</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<!-- Downloaded copies of the CSS files served by GitHub.
     In github.css, the @font-face for font-family:'octicons'
     has been edited to refer to local copies of the font files -->
<link rel="stylesheet" type="text/css" href="github.css"/>
<link rel="stylesheet" type="text/css" href="github2.css"/>
<style>
body {
  margin-top: 1em;
}
</style>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";

var repo = location.search.substring(1);

// Get Markdown, then render it as HTML
function getThenRenderMarkdown() {
  var xhr = new XMLHttpRequest();
  xhr.open("GET", repo + "/" + README_FILE_NAME, true);
  xhr.responseType = "text";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
     // Response text contains Markdown
      renderMarkdown(this.responseText);
    }
  }
  xhr.send();
}

// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
  xhr.responseType = "html";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
      document.getElementById("readme-content").innerHTML = this.response;
    }
  }
  xhr.send(markdown);
}

window.onload = getThenRenderMarkdown;
//]]>
</script>
</head>
<body>
<!-- The following HTML structure was copied from live GitHub page on 2015-12-01,
     except for the "readme-content" id of the article element,
     which was coined for this preview page.-->
<div class="main-content" role="main">
<div class="container repo-container new-discussion-timeline experiment-repo-nav">
<div class="repository-content">
<div id="readme" class="boxed-group flush clearfix announce instapaper_body md">
<h3><span class="octicon octicon-book"></span>README.md</h3>
<article class="markdown-body entry-content"
         itemprop="mainContentOfPage"
         id="readme-content"><p>Rendering markdown...</p></article>
</div>
</div>
</div>
</div>
</body>
</html>

Vous voudrez peut-être jeter un œil à celui-ci:

https://github.com/kristjanjansen/md2html

Pour Githubou Bitbucketthème, pourrait utiliser l'éditeur en ligne mattstow , url: http://writeme.mattstow.com

Pour les utilisateurs de Visual Studio (pas VS CODE).

Installer l' extension Markdown Editor

De cette façon, lorsque vous ouvrez un fichier README.md, vous aurez un aperçu en direct sur le côté droit.

Une simple recherche sur le Web en donne un à plusieurs: https://stackedit.io/

Markdown Preview , le plugin pour Sublime Text mentionné dans un commentaire précédent n'est plus compatible avec ST2, mais ne prend en charge que Sublime Text 3 (depuis le printemps 2018).

Ce qui est bien à ce sujet: il prend en charge GFM, GitHub Flavored Markdown , qui peut faire un peu plus que Markdown normal. C'est important si vous voulez savoir exactement à quoi ressembleront vos .mds sur GH. _{^{(Y compris ce petit renseignement car l'OP n'a pas ajouté lui-même la balise GFM, et ceux qui recherchent une solution ne le savent peut-être pas non plus.)}}

Vous pouvez l'utiliser avec l'API GitHub si vous êtes en ligne, mais vous devez obtenir un jeton d'accès personnel à cet effet car les appels d'API sans authentification sont limités. Il y a plus d'informations sur l' analyse de GFM dans les documents du plugin.

Si vous utilisez Pycharm (ou un autre IDE Jetbrains comme Intellij, RubyMine, PHPStorm, etc.), il existe plusieurs plugins gratuits pour le support Markdown directement dans votre IDE qui permettent un aperçu en temps réel lors de l'édition. Le plugin Markdown Navigator est assez bon. Si vous ouvrez un fichier .md dans l'EDI, les versions récentes vous proposeront d'installer des plugins de support et vous montreront la liste.

SublimeText 2/3

Installer le paquet: Markdown Preview

Options:

• Aperçu dans le navigateur.
• Exporter en html.
• Copier dans le presse-papier.

Utilisez Jupyter Lab .

Pour installer Jupyter Lab, saisissez ce qui suit dans votre environnement:

pip install jupyterlab

Après l'installation, accédez à l'emplacement de votre fichier de démarque, cliquez avec le bouton droit sur le fichier, sélectionnez "Ouvrir avec" puis cliquez sur "Aperçu de la démarque".

Pour Visual Studio Code, j'utilise

Markdown Preview Enhanced extension.

ReText est un bon visualiseur / éditeur de démarques léger.

^{ReText avec Live Preview (source: ReText; cliquez sur l'image pour une variante plus grande)}

Je l'ai trouvé grâce à Izzy qui a répondu /softwarerecs/17714/simple-markdown-viewer-for-ubuntu (les autres réponses mentionnent d'autres possibilités)

J'utilise markdownlivepreview:
https://markdownlivepreview.com/

C'est très facile, simple et rapide.

MarkdownViewerPlusPlus est un plug- in "[...] Notepad ++ pour afficher un fichier Markdown rendu à la volée

• Panneau ancrable (bascule) avec un HTML rendu du fichier / onglet actuellement sélectionné
• Conforme à CommonMark (0,28)
• Défilement synchronisé
• Intégration CSS personnalisée
• Exportation HTML et PDF
• Notepad ++ Unicode Plugin [...] "

Vous pouvez utiliser l' éditeur de site statique : avec GitLab 13.0 (mai 2020) , il est livré avec un panneau WYSIWYG.

WYSIWYG pour l'éditeur de site statique

Markdown est une syntaxe puissante et efficace pour la création de contenu Web, mais même les auteurs chevronnés de contenu Markdown peuvent avoir du mal à se souvenir de certaines des options de formatage les moins fréquemment utilisées ou à écrire des tableaux même moyennement complexes.
Il y a des tâches mieux accomplies avec un texte riche, «ce que vous voyez est ce que vous obtenez» (WYSIWYG) éditeur.

GitLab 13.0 apporte une expérience de création WYSIWYG Markdown à l'éditeur de site statique avec des options de formatage pour les options de formatage courantes comme les en-têtes, les caractères gras, l'italique, les liens, les listes, les citations et les blocs de code.

L'éditeur WYSIWYG supprime également la lourde tâche de modification des tableaux dans Markdown en vous permettant de modifier visuellement les lignes, colonnes et cellules du tableau de la même manière que vous éditez une feuille de calcul. Pour ceux qui écrivent plus confortablement dans Markdown brut, il y a même un onglet pour basculer entre les modes d'édition WYSIWYG et texte brut.

Voir la documentation et le problème .

Encore une fois, vous ne l'utiliseriez que pour écrire votre README: une fois qu'il a l'air bien, vous pouvez le rapporter à votre projet d'origine.
Mais le fait est que vous n'avez plus besoin d'un plug-in d'aperçu de démarquage tiers.

Pour ceux qui souhaitent évoluer sur leurs iPads, j'aime Textastic. Vous pouvez modifier et prévisualiser les fichiers README.md sans connexion Internet, une fois que vous avez téléchargé le document à partir du cloud.