Как я могу проверить, как будет выглядеть мой файл readme.md перед тем, как перейти на github?

236

Я пишу readme для моего проекта github в формате .md. Есть ли способ проверить, как будет выглядеть мой файл readme.md перед тем, как приступить к работе с github?

github markdown github-flavored-markdown Усман Исмаил
источник
4
Я отвечаю на это как комментарий, потому что поток закрыт, и ни одно из решений не отображало таблицы конвейеров так, как это делал github. Веб-решение, которое кажется наиболее близким, находится здесь: pandao.github.io/editor.md/en.html
Donnie D'Amato
В GitLab 13.0 (май 2020 г.) редактор статического сайта для GitLab имеет редактор WYSIWYG. Смотрите мой ответ ниже .
VonC

Ответы:

150

Много способов: если вы на Mac, используйте Mou .

Если вы хотите протестировать в браузере, вы можете попробовать StackEdit , на что указывают @Aaron или Dillinger, так как Notepag сейчас не работает. Лично я использую Dillinger, так как он просто работает и сохраняет все мои документы в локальной базе данных моего браузера.

три
источник
5
dillinger.io также, кажется, сейчас недоступен, хотя он по-прежнему первый в списке, когда вы используете Google «Markdown Online Viewer», так что это может быть только я. Я успешно использовал stackedit.io для предварительного просмотра и редактирования моего readme.md.
Аарон
Диллинджер в порядке. Большую часть времени было нормально.
три
1
StackEdit - отличный инструмент. Спасибо!
Олькунмустафа,
StackEdit форматирует «списки определений», github - нет. StackEdit помещает тройные блоки кода обратной пометки в свою строку (полезно для использования в нумерованных списках), github - нет. Есть и другие отличия. Единственная надежная ставка - пробная версия с ошибкой и удаление ее, когда вы закончите.
Бруно Броноски
1
К сожалению, это не похоже на то, что Mou поддерживает MacOS Mojave (10.14)
Крис Прист
79

Atom прекрасно работает из коробки - просто откройте файл Markdown и нажмите Ctrl + Shift + M, чтобы переключить панель предварительного просмотра Markdown рядом с ним. Он также обрабатывает HTML и изображения.

Скриншот Atom

Брайан Бернс
источник
2
Поскольку у меня были локальные ресурсы, такие как скриншоты приложения, это решение работает лучше всего. Спасибо!
Emadpres
6
Я использую Atom уже год и не знал, что он сможет это сделать! Принесите позор монахини ...
PaulB
варить бочку установить атом
Jmgarnier
В perfs уже был установлен Atom, просто напечатали atom .и щелкнули правой кнопкой мыши на readme>Markdown Preview
Остин
Атом управляет насестом. Ни один из stackedit, Dillinger или typora не поддерживает разборные разделы с помощью HTML- <details>тегов. Atom делает и выглядит лучше остальных.
Дэвид Паркс
35

Этот уже давно доказал свою надежность: http://tmpvar.com/markdown.html

Мотин
источник
Это было хорошее начало, но тогда это не показывает горизонтальные правила ... заброшенные до дальнейших испытаний.
Бен
Хорошо для быстрой проверки, хотя.
Никос Александрис
35

Это довольно старый вопрос, однако, поскольку я наткнулся на него во время поиска в Интернете, возможно, мой ответ будет полезен для других. Я только что нашел очень полезный инструмент CLI для рендеринга GitHub со вкусом уценки: grip . Он использует API GitHub, поэтому рендеринг довольно хорошо.

Честно говоря, разработчик grip имеет более сложный ответ на эти очень похожие вопросы:

aleimba
источник
2
Спасибо! Приятно не прерывать мой рабочий процесс и открывать другой редактор или переходить на другой веб-сайт
oneWorkingHeadphone
1
Это должен быть принятый ответ - он идеален! Просто alt-tab между вашим редактором и браузером, и он автоматически переопределяет уценку, и выглядит точно так же, как на GitHub. Наконец-то приемлемое решение.
Upio
30

Я обычно просто редактирую его на веб-сайте GitHub и нажимаю «Предварительный просмотр» прямо над окном редактирования.

Возможно, это новая функция, которая была добавлена ​​с момента создания этого поста.

Джастин харрис
источник
8
Проблема этого решения в том, что GitHub (пока что) показывает встроенные различия изменений, что делает предварительный просмотр совершенно непригодным, если вы хотите получить представление о том, как выглядят изменения, а не о том, что фактически изменилось.
B12Toaster
2
@ B12Toaster Вы можете создать новый файл в хранилище, используя веб-сайт GitHub (без его сохранения), назвать его xxx.mdи вставить туда свой код. Расширение файла .mdпозволяет просматривать ваши изменения. Вы обновите его после завершения, затем скопируете содержимое файла и вставите его поверх исходного readme.mdфайла.
Махмуд
Дополнительной проблемой является то, что он не отображает все точно. Один конкретный пример: если вы центрируете изображение сверху, используя <div align='center'><img ...></div>его, оно не будет отображаться по центру в предварительном просмотре, оно будет выровнено по левому краю. Вы должны сохранить его, чтобы увидеть его точно, что делает предварительный просмотр ненадежным, на мой взгляд.
AFOC
28

Visual Studio Code имеет возможность редактировать и просматривать изменения MD файла. Поскольку VS Code не зависит от платформы, это будет работать для Windows, Mac и Linux.

Для переключения между видами нажмите Ctrl + Shift + V в редакторе. Вы можете просматривать предварительный просмотр бок о бок (Ctrl + KV) с файлом, который вы редактируете, и видеть изменения, отраженные в реальном времени при редактировании.

Также...

Q: VS Code поддерживает GitHub Flavored Markdown?

A: Нет, VS Code предназначается для спецификации CommonMark Markdown с использованием библиотеки markdown-it. GitHub движется к спецификации CommonMark.

Подробнее здесь

Нихил Агравал
источник
3
Ницца!! Мне не нужно устанавливать атом!
Аэрин
1
Кстати, я хотел протестировать ссылку на заголовки, используемые GitHub ( stackoverflow.com/a/45860695/5362795 ), и обнаружил, что он также поддерживается VS Code!
Нагев
5

Я использую локально размещенный HTML-файл для предварительного просмотра файлов GitHub.

Я просмотрел несколько существующих вариантов, но решил свернуть свой, чтобы выполнить следующие требования:

  • Отдельный файл
  • Локально размещенный (интранет) URL
  • Расширение браузера не требуется
  • Нет локальной обработки на стороне сервера (например, без PHP)
  • Легкий вес (например, нет JQuery)
  • Высокая точность: используйте GitHub для визуализации Markdown и тот же CSS

Я храню локальные копии своих репозиториев GitHub в одноуровневых каталогах в каталоге "github".

Каждый каталог репо содержит файл README.md:

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

Каталог github содержит HTML-файл предварительного просмотра:

.../github/
           readme.html

Для предварительного просмотра файла readme я просматриваю github / readme.html, указывая репо в строке запроса:

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

Кроме того, вы можете скопировать readme.html в тот же каталог, что и README.md, и опустить строку запроса:

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

Если файл readme.html находится в том же каталоге, что и README.md, вам даже не нужно обслуживать файл readme.html через HTTP: вы можете просто открыть его прямо из своей файловой системы.

HTML-файл использует GitHub API для визуализации Markdown в файле README.md. Существует ограничение скорости : на момент написания 60 запросов в час .

Работает для меня в текущих производственных версиях Chrome, IE и Firefox на Windows 7.

Источник

Вот 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>

Примечания разработчика

  • Как правило, я оборачиваю свой код в IIFE, но в этом случае я не видел необходимости и думал, что буду держать его сжатым
  • Я не удосужился поддержать IE уровня backlevel
  • Для краткости я пропустил код обработки ошибок (вы мне верите ?!)
  • Я бы приветствовал советы по программированию JavaScript

идеи

  • Я подумываю создать GitHub-репозиторий для этого HTML-файла и поместить его в ветку gh-pages, чтобы GitHub использовал его как «обычную» веб-страницу. Я бы настроил файл, чтобы принять полный URL - README (или любой другой файл Markdown) - в качестве строки запроса. Мне любопытно посмотреть, обойдется ли размещение на GitHub в обход ограничения на запросы API GitHub, и столкнулся ли я с междоменными проблемами (используя запрос Ajax для получения Markdown из другого домена, чем домен, обслуживающий страницу HTML) ,

Оригинальная версия (устарела)

Я сохранил эту запись оригинальной версии для любопытства. В этой версии были следующие проблемы, которые решаются в текущей версии:

  • Требуется загрузка некоторых связанных файлов
  • Он не поддерживает удаление в тот же каталог, что и README.md
  • Его HTML был более хрупким; более подвержен изменениям в GitHub

Каталог github содержит HTML-файл «preview» и связанные файлы:

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

Я скачал файлы шрифтов CSS и octicons с 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)

Я переименовал файлы CSS, чтобы опустить длинную строку шестнадцатеричных цифр в исходных именах.

Я отредактировал github.css для ссылки на локальные копии файлов шрифтов octicons.

Я изучил HTML-код страницы GitHub и воспроизвел достаточно структуры HTML, окружающей содержимое readme, чтобы обеспечить разумную точность; например, ограниченная ширина.

CSS GitHub, шрифт octicons и HTML-контейнер для содержимого readme являются движущимися целями: мне нужно будет периодически загружать новые версии.

Я играл с использованием CSS из различных проектов GitHub. Например:

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

но в итоге решил использовать CSS от самого GitHub.

Источник

Вот 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>
Грэм Ханнингтон
источник
3

Для пользователей Visual Studio (не VS CODE).

Установить расширение Markdown EditorСкриншот

Таким образом, когда вы откроете файл README.md, вы увидите предварительный просмотр с правой стороны.

введите описание изображения здесь

Гильерме де Хесус Сантос
источник
2

Markdown Preview , плагин для Sublime Text, упомянутый в предыдущем комментарии, больше не совместим с ST2, но поддерживает только Sublime Text 3 (начиная с весны 2018 года).

Что хорошего в этом: он поддерживает GFM, GitHub Flavored Markdown , который может сделать немного больше, чем обычная Markdown. Это актуально, если вы хотите точно знать, как ваши .mdбудут выглядеть на GH. (Включая этот бит информации, потому что OP сами не добавляли тег GFM, и другие, ищущие решение, могут и не знать об этом.)

Вы можете использовать его с GitHub API, если вы подключены к Интернету, хотя для этого вы должны получить личный токен доступа, поскольку вызовы API без аутентификации ограничены. Там больше информации о разборе GFM в документации плагина.

Кей
источник
1

Если вы используете Pycharm (или другую Jetbrains IDE, такую ​​как Intellij, RubyMine, PHPStorm и т. Д.), Есть несколько бесплатных плагинов для поддержки Markdown прямо в вашей IDE, которые позволяют просматривать в реальном времени при редактировании. Плагин Markdown Navigator довольно хорош. Если вы откроете файл .md в IDE, последние версии предложат установить поддерживающие плагины и покажут вам список.

randalv
источник
1

SublimeText 2/3

Установить пакет: Markdown Preview

Параметры:

  • Предварительный просмотр в браузере.
  • Экспорт в HTML.
  • Скопировать в буфер обмена.
alditis
источник
Это хорошо работает, потому что поддерживает github, gitlab и универсальную уценку. Хотя это сложно установить.
Абель
0

Используйте Jupyter Lab .

Чтобы установить Jupyter Lab, введите в своей среде следующее:

pip install jupyterlab

После установки перейдите к местоположению файла уценки, щелкните файл правой кнопкой мыши, выберите «Открыть с помощью», затем нажмите «Предварительный просмотр уценки».

k0L1081
источник
0

Для кода Visual Studio я использую

Markdown Preview Улучшенное расширение.

Олусола Омосола
источник
0

ReText - хороший легкий просмотрщик / редактор уценки.

ReText с Live Preview
ReText с Live Preview (источник: ReText; щелкните изображение, чтобы увеличить его)

Я нашел это благодаря Иззи, который ответил на /softwarerecs/17714/simple-markdown-viewer-for-ubuntu (другие ответы упоминают другие возможности)

восстанавливающая активность
источник
Обратите внимание, что ReText не поддерживает CommonMark, см. Github.com/retext-project/retext/issues/253
dpi
0

MarkdownViewerPlusPlus - это [...] плагин Notepad ++ для просмотра файла Markdown, отображаемого на лету.

  • Закрепляемая панель (переключатель) с отображаемым HTML-файлом выбранного в данный момент файла / вкладки
  • CommonMark совместимый (0,28)
  • Синхронизированная прокрутка
  • Пользовательская интеграция CSS
  • HTML и PDF Экспорт
  • Блокнот ++ Плагин Unicode [...] "
rob2universe
источник
0

Вы можете использовать статический редактор сайтов : с GitLab 13.0 (май 2020) он поставляется с панелью WYSIWYG.

WYSIWYG для редактора статического сайта

Markdown - это мощный и эффективный синтаксис для создания веб-контента, но даже опытные авторы контента Markdown могут изо всех сил пытаться вспомнить некоторые из менее часто используемых параметров форматирования или писать даже умеренно сложные таблицы с нуля.
Есть некоторые работы, которые лучше выполнять с помощью расширенного текста, редактора «Что видишь, то и получаешь» (WYSIWYG).

GitLab 13.0 предоставляет возможность редактирования WYSIWYG Markdown для редактора статических сайтов с параметрами форматирования для общих параметров форматирования, таких как заголовки, полужирный шрифт, курсив, ссылки, списки, цитаты и кодовые блоки.

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

Редактор WYSIWYG также устраняет обременительную задачу редактирования таблиц в Markdown, позволяя визуально редактировать строки, столбцы и ячейки таблицы так же, как при редактировании электронной таблицы. Для тех, кому удобнее писать в сыром Markdown, есть даже вкладка для переключения между режимами редактирования WYSIWYG и обычного текста.

Смотрите документацию и выпуск .

Опять же, вы должны использовать его только для написания своего README: как только он выглядит хорошо, вы можете сообщить об этом обратно в ваш оригинальный проект.
Но суть в том, что вам больше не нужен плагин предварительного просмотра уценок сторонних производителей.

VonC
источник
-1

Для тех, кто хочет развиваться на своих iPad, мне нравится Textastic. Вы можете редактировать и просматривать файлы README.md без подключения к Интернету после загрузки документа из облака.

ztalbot
источник