Comment puis-je tester l'apparence de mon fichier readme.md avant de m'engager dans github?
J'écris un fichier readme pour mon projet github au format .md. Existe-t-il un moyen de tester l’aspect de mon fichier readme.md avant de s’engager dans github?
Plusieurs façons: Si vous êtes sur un Mac, utilisez Mou .
Si vous voulez tester dans un navigateur, vous pouvez essayer StackEdit , comme l'a souligné @Aaron ou Dillinger puisque Notepag semble être en panne maintenant. Personnellement, j'utilise Dillinger car cela fonctionne et enregistre tous mes documents dans la base de données locale de mon navigateur.
Atom fonctionne parfaitement - il suffit d'ouvrir le fichier Markdown et d'appuyer sur Ctrl + Maj + M pour faire basculer le panneau de prévisualisation Markdown à côté. Il gère le HTML et les images aussi.
Celui-ci a fait ses preuves depuis un certain temps: http://tmpvar.com/markdown.html
Habituellement, je le modifie directement sur le site Web de GitHub, puis cliquez sur "Aperçu" juste au-dessus de la fenêtre d'édition.
C'est peut-être une nouvelle fonctionnalité qui a été ajoutée depuis la publication de cet article.
C'est une question assez ancienne, cependant, puisque je suis tombé dessus en cherchant sur Internet, ma réponse est peut-être utile aux autres… .. Je viens de trouver un outil CLI très utile pour le rendu du markdown aromatisé GitHub: grip . Il utilise l'API de GitHub, donc le rendu est très bon.
Franchement, le développeur de grip a une réponse plus élaborée à ces questions très similaires:
Code Visual Studio a la possibilité d’éditer et de prévisualiser les modifications apportées au fichier md. Puisque 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 + K V) avec le fichier que vous modifiez et voir les modifications reflétées en temps réel à mesure que vous les modifiez.
Également...
Q: Est-ce que VS Code prend en charge GitHub Flavored Markdown?
R: Non, VS Code cible la spécification CommonMark Markdown à l'aide de la bibliothèque markdown-it. GitHub se rapproche de la spécification CommonMark.
Vous voudrez peut-être jeter un coup d'œil à celui-ci:
Sur le Web, utilisez Dillinger . C'est génial.
J'utilise un fichier HTML hébergé localement pour prévisualiser les readmes 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 même CSS
Je conserve des copies locales de mes référentiels GitHub dans des répertoires frères sous un répertoire "github".
Chaque répertoire de référentiel contient un fichier README.md:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
Le répertoire github contient le fichier HTML "preview":
.../github/
readme.html
Pour prévisualiser un fichier lisez-moi, je navigue dans github/readme.html, en spécifiant le référentiel dans la chaîne de requête:
http://localhost/github/readme.html?repo-a
Sinon, vous pouvez copier le fichier lisezmoi.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 GitHub API pour rendre le Markdown dans un fichier README.md. Il y a un limite de débit : au moment de la rédaction, 60 demandes par heure.
Fonctionne pour moi dans les versions de production actuelles de Chrome, IE et Firefox sous 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 du développeur
- En règle générale, j'emballe mon code dans un IIFE, mais dans ce cas, je n'en voyais pas le besoin et je pensais le garder concis.
- Je n'ai pas pris la peine de supporter IE de niveau arrière
- Par souci de concision, j’ai omis le code de traitement des erreurs (me croyez-vous?)
- J'accepterais des astuces de programmation JavaScript
Des idées
- J'envisage de créer un référentiel GitHub pour ce fichier HTML et de le placer dans la branche gh-pages, afin que GitHub le serve de page Web "normale". J'adapterais le fichier pour accepter une URL complète - de README (ou tout autre fichier Markdown) - en tant que chaîne de requête. Je suis curieux de voir si le fait d'être hébergé par GitHub contournerait la limite de requêtes de l'API GitHub et si j'exécutais un nombre important de problèmes interdomaines (en utilisant une requête Ajax pour obtenir le Markdown d'un domaine différent du domaine servant la page HTML) .
Version originale (obsolète)
J'ai conservé cet enregistrement de la version d'origine à des fins de curiosité . Cette version présentait les problèmes suivants, qui sont résolus dans la version actuelle:
- Il fallait télécharger certains fichiers associés
- Il ne supportait pas d'être déposé dans le même répertoire que README.md
- Son code HTML était plus fragile. plus susceptible aux changements dans GitHub
Le répertoire github contient le fichier HTML "preview" 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 polices 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 polices octicons.
J'ai examiné le code HTML d'une page GitHub et reproduit suffisamment de la structure HTML entourant le contenu du fichier Lisez-moi pour fournir une fidélité raisonnable. par exemple, la largeur contrainte.
Le CSS GitHub, la police octicons et le "conteneur" HTML pour le contenu Lisez-moi sont des cibles mobiles: je devrai télécharger périodiquement les 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>
Pour les thèmes Github ou Bitbucket, vous pouvez utiliser l'éditeur en ligne mattstow, url: http://writeme.mattstow.com
Une simple recherche sur le Web en donne à beaucoup d’hérois: https://stackedit.io/
Markdown Preview , le plug-in de Sublime Text mentionné dans un commentaire précédent n'est plus compatible avec ST2, mais ne supporte que Sublime Text 3 (depuis le printemps 2018 ).
Ce qui est intéressant à ce sujet: il prend en charge GFM, GitHub Flavored Markdown , qui peut faire un peu plus que Markdown classique. Ceci est pertinent si vous voulez savoir à quoi ressemblera votre .mds sur GH. (L'inclusion de cette information étant donné que l'OP n'a pas ajouté l'étiquette GFM elle-même et que d'autres personnes à la recherche d'une solution pourraient ne pas en être conscientes non plus.)
Vous pouvez l’utiliser avec l’API GitHub si vous êtes en ligne, mais vous devriez obtenir un jeton d’accès personnel parce que les appels d’API sans authentification sont limités. Il y a plus d'informations sur Parsing GFM dans la documentation du plugin.
Si vous utilisez Pycharm (ou un autre Jetbrains IDE tel qu'Intellij, RubyMine, PHPStorm, etc.), plusieurs plugins gratuits pour le support de Markdown directement dans votre IDE 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, des versions récentes vous proposeront d'installer des plugins de support et de vous montrer la liste.
SublimeText 2/3
Paquet d'installation: Markdown Preview
Options:
- Aperçu dans le navigateur.
- Exporter au format HTML.
- Copier dans le presse-papier.
ReText est un bon visualiseur/éditeur de markdown.
ReText avec aperçu en direct (source: ReText; cliquez sur l'image pour l'agrandir)
Je l'ai trouvé grâce à Izzy qui a répondu https://softwarerecs.stackexchange.com/questions/17714/simple-markdown-viewer-for-ubuntu (d'autres réponses mentionnent d'autres possibilités)
Pour Visual Studio Code, j'utilise
Markdown Preview Extension améliorée.
J'utilise markdownlivepreview:
https://markdownlivepreview.com/
C'est très facile, simple et rapide.
Pour les utilisateurs de Visual Studio (pas VS CODE).
Installer Markdown Editor extension 
Ainsi, lorsque vous ouvrez un fichier README.md, vous obtenez un aperçu en direct sur le côté droit.
Utilisez Jupyter Lab .
Pour installer Jupyter Lab, tapez ce qui suit dans votre environnement:
pip install jupyterlab
Après l'installation, accédez à l'emplacement de votre fichier de démarquage, cliquez dessus avec le bouton droit de la souris, sélectionnez "Ouvrir avec", puis cliquez sur "Aperçu du démarquage".