Jak mogę sprawdzić, jak będzie wyglądał mój plik readme.md przed przystąpieniem do github?

234

Piszę plik Readme dla mojego projektu github w formacie .md. Czy istnieje sposób, aby sprawdzić, jak będzie wyglądał mój plik readme.md przed uruchomieniem github?

github markdown github-flavored-markdown Usman Ismail
źródło
4
Odpowiadam na to jako komentarz, ponieważ wątek jest zamknięty i żadne z rozwiązań nie renderuje tabel potoków w taki sam sposób jak github. Najbliższe rozwiązanie internetowe znajduje się tutaj: pandao.github.io/editor.md/en.html
Donnie D'Amato
W GitLab 13.0 (maj 2020) statyczny edytor strony dla GitLab ma edytor WYSIWYG. Zobacz moją odpowiedź poniżej .
VCC

Odpowiedzi:

149

Wiele sposobów: jeśli używasz komputera Mac, użyj Mou .

Jeśli chcesz przetestować w przeglądarce, możesz wypróbować StackEdit , jak wskazał @Aaron lub Dillinger, ponieważ Notepag wydaje się teraz nieczynny. Osobiście używam Dillingera, ponieważ po prostu działa i zapisuje wszystkie moje dokumenty w lokalnej bazie danych przeglądarki.

trzy
źródło
5
Wygląda na to, że dillinger.io również nie działa, chociaż nadal jest pierwszym wymienionym, gdy przeglądasz „markdown online viewer”, więc może to być ja. Pomyślnie użyłem stackedit.io do podglądu i edycji mojego readme.md.
Aaron,
Dillinger jest w porządku. Przez większość czasu było ok.
trzy
1
StackEdit to świetne narzędzie. Dziękuję Ci!
Olkunmustafa
StackEdit formatuje „listy definicji”, github nie. StackEdit umieszcza potrójne bloki kodu wstecznego we własnej linii (przydatne do stosowania na listach numerowanych), github tego nie robi. Istnieją inne różnice. Jedynym bezpiecznym zakładem jest próba i błąd z gist i usunięcie go, gdy skończysz.
Bruno Bronosky,
1
Niestety nie wygląda na to, że Mou obsługuje MacOS Mojave (10.14)
Chris Priest
78

Atom działa dobrze po wyjęciu z pudełka - wystarczy otworzyć plik Markdown i nacisnąć Ctrl + Shift + M, aby przełączyć obok niego panel podglądu Markdown. Obsługuje również HTML i obrazy.

Zrzut ekranu Atom

Brian Burns
źródło
2
Ponieważ miałem lokalne zasoby, takie jak zrzuty ekranu aplikacji, to rozwiązanie działa najlepiej. Dzięki!
Emadpres
6
Używam atomu od roku i nie miałem pojęcia, że ​​to może zrobić! Przynieś wstyd zakonnicę ...
PaulB
brew cask install atom
jmgarnier
perfs już zainstalował Atom po prostu wpisał atom .i kliknął readme>Markdown Preview
austin
Atom rządzi kurnikiem. Żadna z obsługiwanych składanych sekcji Stackedit, Dillinger lub typora nie była obsługiwana za pomocą <details>tagów HTML . Atom działa i wygląda lepiej niż reszta do uruchomienia.
David Parks
35

Ten okazał się niezawodny od dłuższego czasu: http://tmpvar.com/markdown.html

Motin
źródło
To był dobry początek, ale ten nie pokazuje zasad horyzontalnych ... porzuconych przed dalszymi testami.
Ben
Miło na szybką kontrolę.
Nikos Alexandris
35

To dość stare pytanie, jednak ponieważ natknąłem się na nie podczas wyszukiwania w Internecie, być może moja odpowiedź jest przydatna dla innych. Właśnie znalazłem bardzo przydatne narzędzie CLI do renderowania Markdown o smaku GitHub: grip . Używa API GitHub, dzięki czemu renderuje się całkiem dobrze.

Szczerze mówiąc, twórca gripu , ma bardziej szczegółową odpowiedź na te bardzo podobne pytania:

aleimba
źródło
2
Dziękuję Ci! Fajnie jest, że nie muszę przerywać pracy i otwierać innego edytora ani wchodzić na inną stronę internetową
oneWorkingHeadphone
1
To powinna być zaakceptowana odpowiedź - jest idealna! Po prostu wciśnij Alt-Tab między edytorem a przeglądarką, a automatycznie wyrenderuje markdown i wygląda dokładnie tak, jak na GitHub. Wreszcie akceptowalne rozwiązanie.
Upio
30

Zwykle po prostu edytuję go bezpośrednio na stronie GitHub i klikam „Podgląd” tuż nad oknem edycji.

Być może jest to nowa funkcja dodana od czasu opublikowania tego postu.

Justin Harris
źródło
8
Problem z tym rozwiązaniem polega na tym, że GitHub (do tej pory) pokazuje różnice w zmianach, co sprawia, że ​​podgląd jest dość bezużyteczny, jeśli chcesz uzyskać wrażenie, jak wyglądają zmiany, a nie to, co faktycznie się zmieniło.
B12Toaster,
2
@ B12Toaster Możesz utworzyć nowy plik w repozytorium za pomocą strony internetowej GitHub (bez zapisywania), nazwać go xxx.mdi wkleić tam swój kod. Rozszerzenie pliku .mdumożliwia podgląd zmian. Będziesz aktualizować po zakończeniu, a następnie skopiuj zawartość pliku i wklej go na oryginalny readme.mdplik.
Mahmoud,
Dodatkowym problemem jest to, że nie wyświetla dokładnie wszystkiego. Jeden konkretny przykład: jeśli wyśrodkowujesz obraz u góry, używając <div align='center'><img ...></div>go, nie pokaże go na środku podglądu, zostanie wyrównany do lewej. Musisz go zapisać, aby zobaczyć dokładnie, co sprawia, że ​​podgląd jest niewiarygodny moim zdaniem.
AFOC
28

Visual Studio Code ma opcję edycji i podglądu zmian w plikach md. Ponieważ VS Code jest niezależny od platformy, działałoby to w systemach Windows, Mac i Linux.

Aby przełączać się między widokami, naciśnij Ctrl + Shift + V w edytorze. Możesz wyświetlić podgląd obok siebie (Ctrl + KV) z edytowanym plikiem i zobaczyć zmiany odzwierciedlone w czasie rzeczywistym podczas edycji.

Również...

P: Czy VS Code obsługuje GitHub Flavored Markdown?

Odp .: Nie, VS Code kieruje się na specyfikację CommonMark Markdown przy użyciu biblioteki markdown-it. GitHub zmierza w kierunku specyfikacji CommonMark.

Więcej informacji tutaj

Nikhil Agrawal
źródło
3
Miły!! Nie muszę instalować atomu !!
Aerin
1
Nawiasem mówiąc, chciałem przetestować link do tytułów używanych przez GitHub ( stackoverflow.com/a/45860695/5362795 ) i stwierdziłem, że jest on również obsługiwany przez VS Code!
Nagev
5

Korzystam z hostowanego lokalnie pliku HTML, aby wyświetlić podgląd readmes GitHub.

Przyjrzałem się kilku istniejącym opcjom, ale postanowiłem wprowadzić własne, aby spełnić następujące wymagania:

  • Pojedynczy plik
  • Hostowany lokalnie (intranet) adres URL
  • Nie wymaga rozszerzenia przeglądarki
  • Brak lokalnie hostowanego przetwarzania po stronie serwera (na przykład brak PHP)
  • Lekki (na przykład brak jQuery)
  • Wysoka wierność: użyj GitHub do renderowania Markdown i tego samego CSS

Przechowuję lokalne kopie moich repozytoriów GitHub w katalogach rodzeństwa w katalogu „github”.

Każdy katalog repozytorium zawiera plik README.md:

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

Katalog github zawiera plik HTML „podglądu”:

.../github/
           readme.html

Aby wyświetlić podgląd pliku readme, przeglądam github / readme.html, podając repo w ciągu zapytania:

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

Alternatywnie możesz skopiować plik readme.html do tego samego katalogu co plik README.md i pominąć ciąg zapytania:

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

Jeśli plik readme.html znajduje się w tym samym katalogu co plik README.md, nie musisz nawet podawać pliku readme.html przez HTTP: możesz po prostu otworzyć go bezpośrednio z systemu plików.

Plik HTML używa interfejsu API GitHub do renderowania Markdown w pliku README.md. Istnieje limit stawek : w momencie pisania 60 wniosków na godzinę .

Działa dla mnie w bieżących wersjach produkcyjnych Chrome, IE i Firefox w systemie Windows 7.

Źródło

Oto plik 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>

Notatki programisty

  • Zazwyczaj zawijam swój kod do pliku IIFE, ale w tym przypadku nie widziałem takiej potrzeby i myślałem, że zachowam zwięzłość
  • Nie przejmowałem się obsługą IE poziomu niższego
  • Dla zwięzłości pominąłem kod obsługi błędów (czy wierzysz mi ?!)
  • Mile widziane wskazówki dotyczące programowania JavaScript

Pomysły

  • Zastanawiam się nad utworzeniem repozytorium GitHub dla tego pliku HTML i umieszczeniem go w gałęzi gh-pages, tak aby GitHub służył jako „normalna” strona internetowa. Poprawię ten plik, aby zaakceptować pełny adres URL - README (lub innego pliku Markdown) - jako ciąg zapytania. Jestem ciekawy, czy hosting przez GitHub ominąłby limit żądań interfejsu API GitHub i czy uruchamiam wiele problemów między domenami (używając żądania Ajax, aby uzyskać Markdown z innej domeny niż domena obsługująca stronę HTML) .

Wersja oryginalna (przestarzała)

Dla zachowania ciekawości zachowałem ten zapis oryginalnej wersji. Ta wersja miała następujące problemy, które zostały rozwiązane w bieżącej wersji:

  • Wymagało to pobrania niektórych powiązanych plików
  • Nie obsługiwał upuszczania do tego samego katalogu, co README.md
  • HTML był bardziej kruchy; bardziej podatny na zmiany w GitHub

Katalog github zawiera plik HTML „podglądu” i powiązane pliki:

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

Pobrałem pliki czcionek CSS i octicons z 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)

Zmieniłem nazwy plików CSS, aby pominąć długi ciąg cyfr szesnastkowych w oryginalnych nazwach.

Edytowałem github.css, aby odnosić się do lokalnych kopii plików czcionek octicons.

Zbadałem HTML strony GitHub i odtworzyłem wystarczająco dużo struktury HTML otaczającej treść pliku readme, aby zapewnić rozsądną wierność; na przykład ograniczona szerokość.

GitHub CSS, czcionka octicons i „kontener” HTML dla treści readme są ruchomymi celami: będę musiał okresowo pobierać nowe wersje.

Bawiłem się przy użyciu CSS z różnych projektów GitHub. Na przykład:

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

ale ostatecznie postanowił użyć CSS z samego GitHub.

Źródło

Oto plik 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>
Graham Hannington
źródło
3

Dla Githublub Bitbucketmotywu można użyć edytora online mattstow , adres URL: http://writeme.mattstow.com

Eric Wang
źródło
3

Dla użytkowników Visual Studio (nie VS CODE).

Zainstaluj rozszerzenie Markdown EditorZrzut ekranu

W ten sposób, gdy otworzysz plik README.md, będziesz mieć podgląd na żywo po prawej stronie.

wprowadź opis zdjęcia tutaj

Guilherme de Jesus Santos
źródło
2

Markdown Preview , wtyczka do Sublime Text wspomniana we wcześniejszym komentarzu nie jest już zgodna z ST2, ale obsługuje tylko Sublime Text 3 (od wiosny 2018 r.).

Co jest w tym dobrego: obsługuje GFM, GitHub Flavored Markdown , który może zrobić coś więcej niż zwykłe Markdown. Ma to znaczenie, jeśli chcesz .mddokładnie wiedzieć, jak będą wyglądać Twoje dane na GH. (Uwzględniając ten kawałek informacji, ponieważ OP nie dodał tagu GFM, a inni szukający rozwiązania też mogą nie być tego świadomi).

Możesz używać go z interfejsem API GitHub, jeśli jesteś online, ale powinieneś otrzymać osobisty token dostępu do tego celu, ponieważ połączenia API bez uwierzytelnienia są ograniczone. Więcej informacji na temat analizowania GFM znajduje się w dokumentacji wtyczki.

Kay
źródło
1

Jeśli używasz Pycharm (lub innego Jetbrains IDE, takiego jak Intellij, RubyMine, PHPStorm itp.), Istnieje wiele bezpłatnych wtyczek do obsługi Markdown bezpośrednio w twoim IDE, które umożliwiają podgląd w czasie rzeczywistym podczas edycji. Wtyczka Markdown Navigator jest całkiem dobra. Jeśli otworzysz plik .md w IDE, najnowsze wersje zaoferują zainstalowanie obsługiwanych wtyczek i wyświetlenie listy.

randalv
źródło
1

SublimeText 2/3

Zainstaluj pakiet: Markdown Preview

Opcje:

  • Podgląd w przeglądarce.
  • Eksportuj do HTML.
  • Skopiuj do schowka.
zapalenie jelita grubego
źródło
Działa to dobrze, ponieważ obsługuje github, gitlab i ogólne obniżanie wartości. Chociaż jest trudny do zainstalowania.
Abel Callejo
0

Użyj Jupyter Lab .

Aby zainstalować Jupyter Lab, wpisz następujące polecenie w swoim środowisku:

pip install jupyterlab

Po instalacji przejdź do lokalizacji pliku Markdown, kliknij go prawym przyciskiem myszy, wybierz „Otwórz za pomocą”, a następnie kliknij „Podgląd Markdown”.

k0L1081
źródło
0

Używam Visual Studio Code

Rozszerzenie Markdown Preview Enhanced.

Olusola Omosola
źródło
0

ReText to dobra przeglądarka / edytor znaczników .

ReText z podglądem na żywo
ReText z podglądem na żywo (źródło: ReText; kliknij obraz, aby wyświetlić większy wariant)

Znalazłem to dzięki Izzy, który odpowiedział na /softwarerecs/17714/simple-markdown-viewer-for-ubuntu (inne odpowiedzi wspominają o innych możliwościach)

ograniczenie aktywności
źródło
Pamiętaj, że ReText nie obsługuje CommonMark, patrz github.com/retext-project/retext/issues/253
dpi
0

MarkdownViewerPlusPlus to wtyczka „[...] Notepad ++ do wyświetlania pliku Markdown renderowanego w locie

  • Panel dokowalny (przełącznik) z renderowanym HTML aktualnie wybranego pliku / karty
  • Zgodny z CommonMark (0,28)
  • Zsynchronizowane przewijanie
  • Niestandardowa integracja CSS
  • Eksport HTML i PDF
  • Wtyczka Notepad ++ Unicode [...] ”
rob2universe
źródło
0

Możesz użyć statycznego edytora stron : wraz z GitLab 13.0 (maj 2020) , jest on wyposażony w panel WYSIWYG.

WYSIWYG dla Static Site Editor

Markdown to potężna i wydajna składnia do tworzenia treści internetowych, ale nawet doświadczeni autorzy treści Markdown mogą mieć trudności z zapamiętaniem niektórych rzadziej używanych opcji formatowania lub zredagowaniem od podstaw nawet średnio skomplikowanych tabel.
Istnieje kilka zadań, które lepiej wykonać przy użyciu bogatego tekstu, edytora „What You See Is What You Get” (WYSIWYG).

GitLab 13.0 wprowadza edytor WYSIWYG Markdown do Static Site Editor z opcjami formatowania typowych opcji formatowania, takich jak nagłówki, pogrubienie, kursywa, łącza, listy, cytaty i bloki kodu.

https://about.gitlab.com/images/13_0/wysiwyg-markdow-in-sse.png

Edytor WYSIWYG usuwa również uciążliwe zadanie edycji tabel w Markdown, umożliwiając wizualną edycję wierszy, kolumn i komórek tabeli w taki sam sposób, jak edytowałeś arkusz kalkulacyjny. Dla tych bardziej komfortowych pisania w surowym Markdown, jest nawet zakładka do przełączania między WYSIWYG a trybami edycji zwykłego tekstu.

Zobacz dokumentację i problem .

Znowu użyjesz go tylko do napisania README: gdy będzie dobrze wyglądać, możesz zgłosić go z powrotem do oryginalnego projektu.
Ale chodzi o to, że nie potrzebujesz już żadnej wtyczki podglądu zniżek w firmie.

VonC
źródło
-1

Dla tych, którzy chcą rozwijać się na iPadzie, lubię Textastic. Możesz edytować i przeglądać pliki README.md bez połączenia z Internetem, po pobraniu dokumentu z chmury.

ztalbot
źródło