Как создать файл уценки

Обновлено: 01.07.2024

Работа с файлами Markdown в Visual Studio Code проста, понятна и увлекательна. Помимо базового редактирования VS Code, существует ряд специальных функций Markdown, которые помогут вам работать более продуктивно.

Расширения Markdown

В дополнение к функциям, предоставляемым VS Code из коробки, вы можете установить расширение для большей функциональности.

Совет. Нажмите на плитку расширения выше, чтобы прочитать описание и отзывы, чтобы решить, какое расширение лучше всего подходит для вас. Узнайте больше в Marketplace.

Предварительный просмотр уценки

VS Code поддерживает файлы Markdown по умолчанию. Вы просто начинаете писать текст Markdown, сохраняете файл с расширением .md, а затем можете переключать визуализацию редактора между кодом и предварительным просмотром файла Markdown; очевидно, вы также можете открыть существующий файл Markdown и начать с ним работать. Для переключения между представлениями нажмите ⇧⌘V (Windows, Linux Ctrl+Shift+V ) в редакторе. Вы можете просматривать предварительный просмотр рядом ( ⌘K V (Windows, Linux Ctrl+K V ) ) с редактируемым файлом и видеть, как изменения отражаются в реальном времени по мере редактирования.

Вот пример с очень простым файлом.

< /p>

Совет. Вы также можете щелкнуть правой кнопкой мыши вкладку редактора и выбрать «Открыть предварительный просмотр» ( ⇧⌘V (Windows, Linux Ctrl+Shift+V ) ) или использовать палитру команд ( ⇧⌘P (Windows, Linux Ctrl+Shift+P ) ), чтобы запустить команду Markdown: Open Preview to the Side ( ⌘KV (Windows, Linux Ctrl+KV ) ).

Динамический предварительный просмотр и блокировка предварительного просмотра

По умолчанию предварительный просмотр Markdown автоматически обновляется для предварительного просмотра текущего активного файла Markdown:

Вы можете заблокировать предварительный просмотр Markdown с помощью команды Markdown: Toggle Preview Locking, чтобы он оставался привязанным к текущему документу Markdown. Заблокированные превью обозначаются [Preview] в заголовке:

Синхронизация редактора и предварительного просмотра

VS Code автоматически синхронизирует редактор Markdown и панели предварительного просмотра. Прокрутите предварительный просмотр Markdown, и редактор прокрутится, чтобы соответствовать области просмотра предварительного просмотра. Прокрутите редактор Markdown, и предварительный просмотр будет прокручиваться, чтобы соответствовать его области просмотра:

Вы можете отключить синхронизацию прокрутки с помощью параметров markdown.preview.scrollPreviewWithEditor и markdown.preview.scrollEditorWithPreview.

Выбранная в данный момент строка в редакторе обозначается в предварительном просмотре Markdown светло-серой полосой на левом поле:

Кроме того, двойной щелчок по элементу в предварительном просмотре Markdown автоматически откроет редактор файла и прокрутит до строки, ближайшей к выбранному элементу.

Структура

Представление «Структура» — это отдельный раздел в нижней части Проводника. В развернутом виде он покажет дерево символов активного в данный момент редактора. Для файлов Markdown дерево символов представляет собой иерархию заголовков файла Markdown.

Представление «Структура» — отличный способ просмотреть структуру и структуру заголовка документа.

Расширение предварительного просмотра Markdown

Расширения могут добавлять пользовательские стили и скрипты в предварительный просмотр Markdown, чтобы изменить его внешний вид и добавить новые функции. Вот набор примеров расширений, которые настраивают предварительный просмотр:

Использование собственного CSS

Например, чтобы загрузить таблицу стилей с именем Style.css в корень текущей рабочей области, используйте Файл > Настройки > Настройки, откройте файл settings.json рабочей области и выполните следующее обновление:

Сохраняйте пробелы в конце, чтобы создать разрывы строк

Для создания жестких разрывов строк в Markdown требуется два или более пробела в конце строки. В зависимости от настроек вашего пользователя или рабочей области, VS Code может быть настроен на удаление конечных пробелов. Чтобы сохранить пробелы в конце только в файлах Markdown, вы можете добавить эти строки в свой settings.json :

Безопасность предварительного просмотра Markdown

Когда предварительный просмотр Markdown блокирует содержимое на странице, в правом верхнем углу окна предварительного просмотра отображается всплывающее окно с предупреждением:

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

Настройки безопасности предварительного просмотра Markdown применяются ко всем файлам в рабочей области.

Подробнее о каждом из этих уровней безопасности:

Строгий

Настоятельно рекомендуется оставить строгую защиту включенной, если только у вас нет веской причины для ее изменения И вы доверяете всем файлам Markdown в рабочей области.

Разрешить небезопасный контент

Отключить

Фрагменты для Markdown

Есть несколько встроенных фрагментов кода Markdown, включенных в VS Code. Нажмите ⌃Пробел (Windows, Linux Ctrl+Space ) (триггер предложения), и вы получите контекстно-зависимый список предложений.

Совет. Вы можете добавить свои собственные сниппеты, определяемые пользователем, для Markdown. Взгляните на User Defined Snippets, чтобы узнать, как это сделать.

Компиляция Markdown в HTML

VS Code интегрируется с компиляторами Markdown с помощью встроенного средства запуска задач. Мы можем использовать это для компиляции файлов .md в файлы .html. Давайте рассмотрим создание простого документа Markdown.

Шаг 1. Установите компилятор Markdown

В этом пошаговом руководстве мы используем популярный модуль Node.js, markdown-it.

Примечание. Существует множество компиляторов Markdown, помимо markdown-it. Выберите тот, который лучше всего соответствует вашим потребностям и среде.

Шаг 2. Создайте простой файл MD

Откройте VS Code в пустой папке и создайте файл sample.md.

Примечание. Вы можете открыть папку с VS Code, либо выбрав папку с помощью меню «Файл» > «Открыть папку», либо перейдя в папку и введя «code ». в командной строке.

Поместите в этот файл следующий исходный код:

Шаг 3. Создайте файл tasks.json

Следующий шаг — настроить файл конфигурации задачи tasks.json . Для этого запустите «Терминал» > «Настроить задачи» и нажмите «Создать файл tasks.json из шаблонов». Затем VS Code представляет список возможных шаблонов tasks.json на выбор. Выберите «Другие», так как мы хотим запустить внешнюю команду.

Это создает файл tasks.json в папке .vscode вашей рабочей области со следующим содержимым:

Чтобы использовать markdown-it для компиляции файла Markdown, измените содержимое следующим образом:

Совет. Несмотря на то, что пример предназначен для помощи с общими параметрами конфигурации, IntelliSense также доступен для файла tasks.json, чтобы помочь вам в этом. Используйте ⌃Space (Windows, Linux Ctrl+Space ), чтобы увидеть доступные настройки.

Шаг 4. Запустите задачу сборки

Поскольку в более сложных средах может быть несколько задач сборки, мы предлагаем вам выбрать задачу для выполнения после нажатия ⇧⌘B (Windows, Linux Ctrl+Shift+B ) (Выполнить задачу сборки). Кроме того, мы позволяем вам сканировать вывод на наличие проблем при компиляции. Поскольку мы хотим преобразовать только файл Markdown в HTML, выберите Никогда не сканировать выходные данные сборки из представленного списка.

На этом этапе вы должны увидеть дополнительный файл в списке файлов sample.html .

Если вы хотите сделать задачу Compile Markdown задачей сборки по умолчанию, выполните команду Configure Default Build Task из глобального меню терминала и выберите Compile Markdown из представленного списка. Окончательный файл tasks.json будет выглядеть следующим образом:

Автоматизация компиляции Markdown

Давайте пойдем немного дальше и автоматизируем компиляцию Markdown с помощью VS Code. Мы можем сделать это с помощью той же интеграции средства запуска задач, что и раньше, но с некоторыми изменениями.

Шаг 1. Установите Gulp и несколько подключаемых модулей

Мы используем Gulp для создания задачи, которая автоматизирует компиляцию Markdown. Мы также используем подключаемый модуль gulp-markdown, чтобы немного упростить задачу.

Нам нужно установить gulp как глобально (переключатель -g), так и локально:

Примечание: gulp-markdown-it — это подключаемый модуль Gulp для модуля markdown-it, который мы использовали ранее. Есть много других подключаемых модулей Gulp Markdown, которые вы можете использовать, а также подключаемые модули для Grunt.

Вы можете проверить успешность установки gulp, набрав gulp -v . Вы должны увидеть версию, отображаемую как для глобальной (CLI), так и для локальной установки.

Шаг 2. Создайте простую задачу Gulp

Откройте VS Code в той же папке, что и раньше (содержит sample.md и tasks.json в папке .vscode), и создайте gulpfile.js в корневом каталоге.

Поместите в этот файл следующий исходный код:

Что здесь происходит?

Мы отслеживаем изменения в любом файле Markdown в нашей рабочей области, т. е. в текущей папке, открытой в VS Code.
Мы берем набор файлов Markdown, которые были изменены, и пропускаем их через наш компилятор Markdown, gulp-markdown-it .
Теперь у нас есть набор файлов HTML, каждый из которых назван в честь исходного файла Markdown. Затем мы помещаем эти файлы в тот же каталог.

Шаг 3. Запустите задачу gulp по умолчанию

Чтобы завершить интеграцию задач с VS Code, нам потребуется изменить конфигурацию задачи, чтобы запустить только что созданную задачу Gulp по умолчанию. Вы можете либо удалить файл tasks.json, либо очистить его, сохранив только свойство «версия»: «2.0.0». Теперь выполните Run Task из глобального меню терминала. Обратите внимание, что вам предоставляется средство выбора, в котором перечислены задачи, определенные в файле gulp. Выберите gulp: default, чтобы запустить задачу. Мы позволяем вам сканировать вывод на предмет проблем с компиляцией. Поскольку мы хотим преобразовать только файл Markdown в HTML, выберите «Никогда не сканировать вывод сборки» из представленного списка. На этом этапе, если вы создаете и/или изменяете другие файлы Markdown, вы видите соответствующие сгенерированные HTML-файлы и/или изменения, отраженные при сохранении. Вы также можете включить функцию автосохранения, чтобы упростить процесс.

Если вы хотите сделать задачу gulp: default задачей сборки по умолчанию, выполняемой при нажатии ⇧⌘B (Windows, Linux Ctrl+Shift+B ), запустите Configure Default Build Task из глобального меню терминала и выберите gulp: default из представленный список. Окончательный файл tasks.json будет выглядеть следующим образом:

Шаг 4. Завершите задачу gulp по умолчанию

Задача gulp: default выполняется в фоновом режиме и отслеживает изменения файлов в файлах Markdown. Если вы хотите остановить задачу, вы можете использовать Завершить задачу из глобального меню терминала.

Дальнейшие шаги

Читайте дальше, чтобы узнать о:

- Хотите отредактировать свой CSS? VS Code отлично поддерживает редактирование CSS, SCSS и Less.

Частые вопросы

Есть ли проверка орфографии?

Не устанавливается вместе с VS Code, но есть расширения для проверки орфографии. Посетите VS Code Marketplace, чтобы найти полезные расширения, которые помогут вам в вашем рабочем процессе.

Поддерживает ли VS Code GitHub Flavored Markdown?

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

В приведенном выше пошаговом руководстве я не нашел команду «Настроить задачу» в палитре команд?

Возможно, вы открыли файл в VS Code, а не папку. Вы можете открыть папку, либо выбрав папку с помощью «Файл» > «Открыть папку», либо перейдя к папке и набрав «код». в командной строке.

Обзор Markdown, как он работает и что с ним можно делать.

Что такое уценка?

Markdown – это упрощенный язык разметки, который можно использовать для добавления элементов форматирования в текстовые документы с открытым текстом. Созданный Джоном Грубером в 2004 году язык разметки Markdown сейчас является одним из самых популярных в мире языков разметки.

Использование Markdown отличается от использования редактора WYSIWYG. В таком приложении, как Microsoft Word, вы нажимаете кнопки для форматирования слов и фраз, и изменения сразу видны. Уценка не такая. Когда вы создаете файл в формате Markdown, вы добавляете в текст синтаксис Markdown, чтобы указать, какие слова и фразы должны выглядеть по-другому.

Вы можете добавить элементы форматирования Markdown в текстовый файл с помощью текстового редактора. Или вы можете использовать одно из множества приложений Markdown для операционных систем macOS, Windows, Linux, iOS и Android. Есть также несколько веб-приложений, специально разработанных для записи в Markdown.

В зависимости от используемого приложения предварительный просмотр отформатированного документа в режиме реального времени может быть недоступен. Но это нормально. По словам Грубера, синтаксис Markdown удобен для чтения и ненавязчив, поэтому текст в файлах Markdown можно прочитать, даже если он не отображается.

Основная цель дизайна синтаксиса форматирования Markdown — сделать его как можно более читабельным. Идея заключается в том, что документ в формате Markdown должен публиковаться как есть, как обычный текст, и при этом он не должен выглядеть так, как будто он был размечен тегами или инструкциями по форматированию.

Зачем использовать уценку?

Возможно, вам интересно, почему люди используют Markdown вместо WYSIWYG-редактора. Зачем писать с помощью Markdown, если вы можете нажимать кнопки в интерфейсе для форматирования текста? Как оказалось, есть несколько разных причин, по которым люди используют редакторы Markdown вместо редакторов WYSIWYG.

Markdown можно переносить. Файлы, содержащие текст в формате Markdown, можно открыть практически в любом приложении. Если вы решите, что вам не нравится используемое приложение Markdown, вы можете импортировать файлы Markdown в другое приложение Markdown. Это резко контрастирует с приложениями для обработки текстов, такими как Microsoft Word, которые блокируют ваш контент в проприетарном формате файла.

Markdown не зависит от платформы. Вы можете создавать текст в формате Markdown на любом устройстве с любой операционной системой.

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

Уценка повсюду. Такие веб-сайты, как Reddit и GitHub, поддерживают Markdown, а также множество настольных и веб-приложений.

Пинать шины

Лучший способ начать работу с Markdown — использовать его. Это проще, чем когда-либо прежде, благодаря множеству бесплатных инструментов.

Вам даже не нужно ничего скачивать. Есть несколько онлайн-редакторов Markdown, которые вы можете использовать, чтобы попробовать писать в Markdown. Dillinger — один из лучших онлайн-редакторов Markdown. Просто откройте сайт и начните вводить текст в левой панели. Предварительный просмотр готового документа появится на правой панели.

Возможно, вы захотите, чтобы веб-сайт Dillinger оставался открытым, пока вы читаете это руководство. Таким образом, вы можете попробовать синтаксис, когда узнаете о нем. После того, как вы ознакомитесь с Markdown, вы можете использовать приложение Markdown, которое можно установить на настольный компьютер или мобильное устройство.

Как это работает?

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

Когда вы пишете в Markdown, текст сохраняется в текстовом файле с расширением .md или .markdown. Но тогда что? Как ваш файл в формате Markdown преобразуется в HTML или в готовый к печати документ?

Короткий ответ: вам нужно приложение Markdown, способное обрабатывать файл Markdown. Доступно множество приложений — от простых скриптов до настольных приложений, похожих на Microsoft Word. Несмотря на визуальные различия, все приложения делают одно и то же. Как и Диллинджер, все они преобразуют текст в формате Markdown в HTML, чтобы его можно было отобразить в веб-браузерах.

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

Примечание. Приложение Markdown и процессор — это два отдельных компонента. Для краткости я объединил их в один элемент («Приложение Markdown») на рисунке ниже.

Подводя итог, можно сказать, что этот процесс состоит из четырех частей:

Создайте файл Markdown с помощью текстового редактора или специального приложения Markdown. Файл должен иметь расширение .md или .markdown.
Откройте файл Markdown в приложении Markdown.
Используйте приложение Markdown для преобразования файла Markdown в HTML-документ.
Просмотрите HTML-файл в веб-браузере или используйте приложение Markdown, чтобы преобразовать его в другой формат файла, например PDF.

С вашей точки зрения, процесс будет несколько отличаться в зависимости от используемого вами приложения. Например, Диллинджер по существу объединяет шаги 1-3 в единый бесшовный интерфейс — все, что вам нужно сделать, это ввести текст в левой панели, и визуализированный вывод волшебным образом появится в правой панели. Но если вы используете другие инструменты, такие как текстовый редактор с генератором статических веб-сайтов, вы обнаружите, что процесс гораздо более нагляден.

Для чего хороша уценка?

Markdown – это быстрый и простой способ делать заметки, создавать контент для веб-сайта и создавать документы, готовые к печати.

Изучение синтаксиса Markdown не займет много времени, и как только вы научитесь его использовать, вы сможете писать с использованием Markdown практически везде. Большинство людей используют Markdown для создания контента для Интернета, но Markdown хорош для форматирования всего, от сообщений электронной почты до списков покупок.

Вот несколько примеров того, что вы можете делать с помощью Markdown.

Веб-сайты

Markdown был разработан для Интернета, поэтому неудивительно, что существует множество приложений, специально предназначенных для создания контента веб-сайтов.

Если вы ищете самый простой способ создать веб-сайт с файлами Markdown, попробуйте blot.im. После того, как вы зарегистрируетесь в Blot, на вашем компьютере будет создана папка Dropbox. Просто перетащите файлы Markdown в папку и — пуф! — они есть на вашем сайте.Нет ничего проще.

Если вы знакомы с HTML, CSS и контролем версий, попробуйте Jekyll, популярный генератор статических сайтов, который берет файлы Markdown и создает веб-сайт в формате HTML. Одним из преимуществ этого подхода является то, что GitHub Pages предоставляет бесплатный хостинг для веб-сайтов, созданных Jekyll. Если вам не нравится Jekyll, просто выберите один из многих других доступных генераторов статических сайтов.

Документы

В Markdown нет всех наворотов текстовых процессоров, таких как Microsoft Word, но его достаточно для создания основных документов, таких как задания и письма. Вы можете использовать приложение для создания документов Markdown для создания и экспорта документов в формате Markdown в формат файла PDF или HTML. Часть PDF является ключевой, потому что, когда у вас есть PDF-документ, вы можете делать с ним что угодно — распечатывать, отправлять по электронной почте или загружать на веб-сайт.

Вот некоторые приложения для создания документов Markdown, которые я рекомендую:

Совет. iA Writer предоставляет шаблоны для предварительного просмотра, печати и экспорта документов в формате Markdown. Например, шаблон «Академический — стиль MLA» отступает от абзаца и добавляет двойной интервал между предложениями.

Примечания

Практически во всех отношениях Markdown — идеальный синтаксис для создания заметок. К сожалению, Evernote и OneNote, два самых популярных приложения для заметок, в настоящее время не поддерживают Markdown. Хорошая новость заключается в том, что несколько других приложений для заметок действительно поддерживают Markdown:

— популярное приложение для создания заметок в формате Markdown с множеством функций. — это бесплатное, простое приложение для создания заметок, доступное для любой платформы. это приложение для создания заметок, которое работает на различных платформах. это похожее на Evernote приложение, доступное для устройств Mac и iOS. По умолчанию он не использует исключительно Markdown, но вы можете включить режим совместимости с Markdown. это приложение для создания заметок, которое уважает вашу конфиденциальность. Он доступен для каждой платформы. позиционирует себя как «приложение для создания заметок с открытым исходным кодом, предназначенное для программистов».

Если вы не можете расстаться с Evernote, попробуйте Marxico, редактор Markdown для Evernote на основе подписки, или используйте Markdown Here на веб-сайте Evernote.

Книги

Хотите самостоятельно опубликовать роман? Попробуйте Leanpub, сервис, который берет ваши файлы в формате Markdown и превращает их в электронную книгу. Leanpub выводит вашу книгу в форматах файлов PDF, EPUB и MOBI. Если вы хотите создать копии своей книги в мягкой обложке, вы можете загрузить PDF-файл в другую службу, например Kindle Direct Publishing. Чтобы узнать больше о написании и самостоятельной публикации книги с помощью Markdown, прочитайте этот пост в блоге.

Презентации

Хотите верьте, хотите нет, но вы можете создавать презентации из файлов в формате Markdown. Создание презентаций в Markdown требует некоторого привыкания, но как только вы освоитесь, это будет намного быстрее и проще, чем использование таких приложений, как PowerPoint или Keynote. Remark (проект GitHub) — это популярный браузерный инструмент для создания слайд-шоу Markdown, а также Cleaver (проект GitHub) и Marp (проект GitHub). Если вы используете Mac и предпочитаете использовать приложение, попробуйте Deckset или Hyperdeck.

Электронная почта

Если вы отправляете много сообщений электронной почты и устали от элементов управления форматированием, доступных на большинстве веб-сайтов поставщиков услуг электронной почты, вы будете рады узнать, что есть простой способ писать сообщения электронной почты с помощью Markdown. Markdown Here – это бесплатное расширение для браузера с открытым исходным кодом, которое преобразует текст в формате Markdown в формат HTML, готовый к отправке.

Сотрудничество

Приложения для совместной работы и командного обмена сообщениями – популярный способ общения с коллегами и друзьями на работе и дома. Эти приложения не используют все функции Markdown, но функции, которые они предоставляют, довольно полезны. Например, возможность выделять текст жирным шрифтом и курсивом без использования интерфейса WYSIWYG очень удобна. Slack, Discord, Wiki.js и Mattermost — хорошие приложения для совместной работы.

Документация

Markdown идеально подходит для технической документации. Такие компании, как GitHub, все чаще переходят на Markdown для своей документации — посмотрите их сообщение в блоге о том, как они перенесли свою документацию в формате Markdown на Jekyll. Если вы пишете документацию для продукта или услуги, обратите внимание на эти удобные инструменты:

может создать веб-сайт документации из ваших файлов Markdown с открытым исходным кодом. Просто подключите свой репозиторий GitHub к их сервису и нажмите — Read the Docs сделает все остальное. У них также есть услуга для коммерческих организаций. — это быстрый и простой генератор статических сайтов, предназначенный для создания проектной документации. Исходные файлы документации записываются в формате Markdown и настраиваются с помощью одного файла конфигурации YAML. MkDocs имеет несколько встроенных тем, в том числе порт темы документации Read the Docs для использования с MkDocs. Одна из новейших тем — MkDocs Material. генератор статических сайтов, предназначенный исключительно для создания веб-сайтов с документацией.Он поддерживает переводы, поиск и управление версиями. — это генератор статических сайтов, работающий на Vue и оптимизированный для написания технической документации. упоминалось ранее в разделе о веб-сайтах, но это также хороший вариант для создания веб-сайта документации из файлов Markdown. Если вы пойдете по этому пути, обязательно ознакомьтесь с темой документации Jekyll.

Разновидности Markdown

Один из самых запутанных аспектов использования Markdown заключается в том, что практически каждое приложение Markdown реализует немного отличающуюся версию Markdown. Эти варианты Markdown обычно называются разновидностями. Ваша задача — освоить любой вариант Markdown, реализованный в вашем приложении.

Чтобы лучше понять концепцию разновидностей Markdown, можно подумать о них как о языковых диалектах. Жители Нью-Йорка говорят по-английски так же, как жители Лондона, но между диалектами, используемыми в обоих городах, есть существенные различия. То же самое верно и для людей, использующих различные приложения Markdown. Использование Dillinger для написания с помощью Markdown — это совершенно другой опыт, чем использование Ulysses.

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

Если вы только начинаете, лучший совет, который я могу вам дать, — выбрать приложение Markdown с хорошей поддержкой Markdown. Это будет иметь большое значение для обеспечения переносимости ваших файлов Markdown. Возможно, вы захотите хранить и использовать файлы Markdown в других приложениях, и для этого вам нужно начать с приложения, которое обеспечивает хорошую поддержку. Вы можете использовать каталог инструментов, чтобы найти приложение, которое соответствует всем требованиям.

Дополнительные ресурсы

Существует множество ресурсов, которые можно использовать для изучения Markdown. Вот некоторые другие вводные ресурсы:

. Оригинальное руководство, написанное создателем Markdown. . Веб-сайт с открытым исходным кодом, который позволяет вам попробовать Markdown в веб-браузере. . Список инструментов Markdown и учебных ресурсов. . Серия из нескольких частей, описывающая экосистему для верстки документов Markdown с использованием pandoc и ConTeXt.

Поднимите свои навыки работы с Markdown на новый уровень.

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

Хотите узнать больше о Markdown?

Не останавливайтесь сейчас! 🚀 Пометьте репозиторий GitHub, а затем введите свой адрес электронной почты ниже, чтобы получать новые руководства по Markdown по электронной почте. Никакого спама!

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

Когда вы используете два или более заголовков, GitHub автоматически создает оглавление, доступ к которому можно получить, нажав

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

Вы можете выделять жирным шрифтом, курсивом или зачеркивать текст в полях комментариев и файлах .md.

< td>* * или _ _

Стиль	Синтаксис	Сочетание клавиш	Пример	Вывод
Полужирный	или __ __	Command + B (Mac) или Ctrl + B ( Windows/Linux)	Это жирный текст	Это жирный текст
Курсив	Command + I (Mac) или Ctrl + I (Windows/Linux)	Этот текст выделен курсивом	< em>Этот текст выделен курсивом
Зачеркнутый	~~ ~~	~~Это ошибочный текст~ ~	Это ошибочный текст
Жирный и вложенный курсив	и _ _	Этот текст _чрезвычайно_ важен	Этот текст чрезвычайно важен
Выделено жирным шрифтом и курсивом	* *	*Весь этот текст важен*	Весь этот текст важен

Вы можете цитировать текст с помощью > .

Совет. При просмотре беседы вы можете автоматически цитировать текст комментария, выделив текст и нажав R . Вы можете процитировать весь комментарий, нажав

, затем Цитировать ответ. Дополнительную информацию о сочетаниях клавиш см. в разделе "Сочетания клавиш".

Вы можете вызвать код или команду в предложении с помощью одиночных обратных кавычек. Текст внутри обратных кавычек форматироваться не будет. Вы также можете нажать сочетание клавиш Command + E (Mac) или Ctrl + E (Windows/Linux), чтобы вставить обратные кавычки для блока кода в строке Markdown.

Чтобы преобразовать код или текст в отдельный блок, используйте тройные обратные кавычки.

Если вы часто редактируете фрагменты кода и таблицы, вам может быть полезно включить шрифт фиксированной ширины во всех полях комментариев на GitHub. Дополнительные сведения см. в разделе «Включение шрифтов фиксированной ширины в редакторе».

Вы можете создать встроенную ссылку, заключив текст ссылки в квадратные скобки [ ], а затем заключив URL-адрес в скобки ( ). Вы также можете использовать сочетание клавиш Command + K, чтобы создать ссылку. Выделив текст, вы можете вставить URL-адрес из буфера обмена, чтобы автоматически создать ссылку из выделенного.

Совет. GitHub автоматически создает ссылки, если в комментарии указаны действительные URL-адреса. Дополнительную информацию см. в разделе "Автосвязанные ссылки и URL-адреса".

Вы можете напрямую сослаться на раздел в обработанном файле, наведя указатель мыши на заголовок раздела, чтобы отобразить ссылку:

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

Относительная ссылка — это ссылка, относящаяся к текущему файлу. Например, если у вас есть файл README в корне репозитория и другой файл в docs/CONTRIBUTING.md, относительная ссылка на CONTRIBUTING.md в вашем README может выглядеть так:

GitHub автоматически преобразует относительную ссылку или путь к изображению в зависимости от ветки, в которой вы сейчас находитесь, чтобы ссылка или путь всегда работали. Вы можете использовать все операнды относительных ссылок, такие как ./ и ../ .

Относительные ссылки удобнее для пользователей, клонирующих ваш репозиторий. Абсолютные ссылки могут не работать в клонах вашего репозитория — мы рекомендуем использовать относительные ссылки для ссылки на другие файлы в вашем репозитории.

Вы можете отобразить изображение, добавив ! и заключить замещающий текст в [ ] . Затем заключите ссылку на изображение в круглые скобки () .

GitHub поддерживает встраивание изображений в задачи, запросы на вытягивание, обсуждения, комментарии и файлы .md. Вы можете отобразить изображение из своего репозитория, добавить ссылку на онлайн-изображение или загрузить изображение. Дополнительную информацию см. в разделе "Загрузка ресурсов".

Совет. Если вы хотите отобразить изображение, находящееся в вашем репозитории, используйте относительные ссылки вместо абсолютных.

Вот несколько примеров использования относительных ссылок для отображения изображения.

Контекст	Относительная ссылка
В файле .md на та же ветка	/assets/images/electrocat.jpg
В файле .md в другой ветке	/../ main/assets/images/electrocat.jpg
В задачах пулреквесты и комментарии репозитория	../blob/main/assets/images /electrocat.jpg
В файле .md в другом репозитории	/../../../../github/docs/ blob/main/assets/images/electrocat.jpg
В задачах пулреквесты и комментарии другого репозитория	../../.. /github/docs/blob/main/assets/images/electrocat.jpg?raw=true

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

Дополнительную информацию см. в разделе "Относительные ссылки".

Указание темы, в которой отображается изображение

Мы различаем светлые и темные цветовые режимы, поэтому доступны два варианта. Вы можете использовать эти параметры для отображения изображений, оптимизированных для темного или светлого фона. Это особенно полезно для прозрачных изображений PNG.

Вы можете создать неупорядоченный список, поставив перед одной или несколькими строками текста знак - или * .

Чтобы упорядочить список, поставьте перед каждой строкой число.

Вы можете создать вложенный список, поместив один или несколько элементов списка ниже другого элемента.

Чтобы создать вложенный список с помощью веб-редактора на GitHub или текстового редактора с моноширинным шрифтом, например Atom, вы можете визуально выровнять список. Введите символы пробела перед элементом вложенного списка, пока символ маркера списка ( - или * ) не окажется непосредственно под первым символом текста в элементе над ним.

Чтобы создать вложенный список в редакторе комментариев на GitHub, который не использует моноширинный шрифт, вы можете посмотреть на элемент списка непосредственно над вложенным списком и подсчитать количество символов, которые появляются перед содержимым элемента. . Затем введите это количество пробелов перед элементом вложенного списка.

В этом примере вы можете добавить вложенный элемент списка под элементом списка 100. Первый элемент списка, установив отступ для вложенного элемента списка не менее пяти пробелов, поскольку перед первым элементом списка есть пять символов ( 100. ).< /p>

Вы можете создать несколько уровней вложенных списков, используя один и тот же метод. Например, поскольку первый элемент вложенного списка содержит семь символов ( ␣␣␣␣␣-␣ ) перед содержимым вложенного списка. Первый элемент вложенного списка , вам потребуется сделать отступ во втором элементе вложенного списка на семь пробелов.

Чтобы создать список задач, ставьте перед элементами списка дефис и пробел, а затем [ ] . Чтобы пометить задачу как выполненную, используйте [x].

Если описание элемента списка задач начинается со скобки, вам нужно экранировать его с помощью \ :

- [ ] \(Необязательно) Открыть дополнительный выпуск

Дополнительную информацию см. в разделе "О списках задач".

Упоминание людей и команд

Вы можете упомянуть человека или команду на GitHub, набрав @ и их имя пользователя или название команды. Это вызовет уведомление и привлечет их внимание к разговору. Люди также получат уведомление, если вы отредактируете комментарий, чтобы упомянуть их имя пользователя или название команды. Дополнительные сведения об уведомлениях см. в разделе "Об уведомлениях".

@github/support Что вы думаете об этих обновлениях?

Когда вы упоминаете родительскую команду, участники ее дочерних команд также получают уведомления, что упрощает общение с несколькими группами людей. Дополнительные сведения см. в разделе "О командах".

При вводе символа @ открывается список людей или команд, работающих над проектом. Список фильтруется по мере ввода, поэтому, как только вы найдете имя человека или команды, которую ищете, вы можете использовать клавиши со стрелками, чтобы выбрать его, и нажать либо вкладку, либо ввод, чтобы завершить имя. Для команд введите @organization/team-name, и все члены этой команды подпишутся на беседу.

Результаты автозаполнения доступны только соавторам репозитория и любым другим участникам ветки.

Ссылки на проблемы и запросы на вытягивание

Ссылки на внешние ресурсы

Если для репозитория настроены пользовательские ссылки автоссылки, то ссылки на внешние ресурсы, такие как задача JIRA или тикет Zendesk, преобразуются в сокращенные ссылки. Чтобы узнать, какие автоссылки доступны в вашем репозитории, обратитесь к кому-нибудь с правами администратора репозитория. Дополнительную информацию см. в разделе «Настройка автоматических ссылок на внешние ресурсы».

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

Вы можете добавить эмодзи в текст, набрав :EMOJICODE: .

@octocat :+1: Этот PR выглядит великолепно — он готов к слиянию! :шипит:

Ввод: откроется список предлагаемых эмодзи. Список будет фильтроваться по мере ввода, поэтому, когда вы найдете нужный смайлик, нажмите Tab или Enter, чтобы завершить выделенный результат.

Полный список доступных эмодзи и кодов см. в Шпаргалке по эмодзи.

Вы можете создать новый абзац, оставив пустую строку между строками текста.

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

Сноска будет отображаться следующим образом:

< бр />

Примечание. Положение сноски в уценке не влияет на то, где она будет отображаться. Вы можете написать сноску сразу после ссылки на сноску, и сноска все равно будет отображаться внизу Markdown.

Скрытие контента с комментариями

Вы можете попросить GitHub скрыть контент из отображаемой Markdown, поместив контент в комментарий HTML.

Игнорирование форматирования Markdown

Вы можете указать GitHub игнорировать (или экранировать) форматирование Markdown, используя \ перед символом Markdown.

Давайте переименуем \*наш-новый-проект\* в \*наш-старый-проект\*.

Для получения дополнительной информации см. "Синтаксис уценки" Daring Fireball.

Отключение рендеринга Markdown

При просмотре файла Markdown вы можете нажать

в верхней части файла, чтобы отключить рендеринг Markdown и вместо этого просмотреть исходный код файла.

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

Помогите нам сделать эти документы лучше!

Все документы GitHub имеют открытый исходный код. Видите что-то неправильное или непонятное? Отправьте запрос на вытягивание.

Файл ReadMe — это стандартное место для инструкций или документации, которыми вы хотите поделиться с людьми о репозитории. Вот как добавить файл ReadMe в репозиторий Git.

Создать файл ReadMe

<р>1. Создайте файл с именем README.md в корневой папке репозитория Git.
2. Добавьте любые инструкции или документацию, которыми вы хотите поделиться с другими. Используйте Markdown для форматирования заголовков, списков, ссылок и т. д. Вот несколько руководств по синтаксису Markdown:

<р>3. Когда закончите, зафиксируйте изменения и отправьте их в удаленное репо. GitHub и Bitbucket отобразят красиво оформленный файл ReadMe на странице проекта репозитория.

Что такое уценка?

Markdown можно преобразовать в другие форматы (например, HTML), и он используется во многих вещах. Это стандартный формат для файлов ReadMe в Git.

Джон Грубер из Daring Fireball (daringfireball.net) создал Markdown. Он говорит: «Markdown должен быть настолько простым для чтения и записи, насколько это возможно. Синтаксис Markdown предназначен для одной цели: его можно использовать в качестве формата для написания в Интернете».

Выйти за рамки Git

Git — это важный инструмент для совместной работы с другими программистами. Изучите Git и многое другое на наших курсах и учебных курсах по программированию:

Связанные ресурсы

<Р>

< бр />

Как создать репозиторий Git: git init

Репозиторий Git (сокращенно репозиторий) содержит все файлы проекта и всю историю изменений. Изучите команду Git, чтобы создать репозиторий.

Основы командной строки Git

Несмотря на то, что через интерфейс командной строки можно сделать многое, главное, что вам нужно знать, как это сделать в Git, — это перейти к папке.

Файлы этапа и фиксации: git add, git commit и git log

Представьте, что Git хранит список изменений в файлах. Итак, как мы можем сказать Git записать наши изменения? Каждое записанное изменение файла (или набора файлов) называется фиксацией. Прочтите, чтобы узнать больше.

README – это текстовый файл, который знакомит с проектом и объясняет его. Он содержит информацию, которая обычно требуется для понимания сути проекта.

Зачем мне это делать?

Это простой способ ответить на вопросы, которые могут возникнуть у вашей аудитории относительно того, как установить и использовать ваш проект, а также о том, как сотрудничать с вами.

Кто должен это сделать?

Любой, кто работает над проектом по программированию, особенно если вы хотите, чтобы другие использовали его или вносили свой вклад.

Когда я должен это сделать?

Определенно, прежде чем показывать проект другим людям или делать его общедоступным. Возможно, вы захотите сделать его первым файлом, который вы создаете в новом проекте.

Куда его поместить?

В каталоге верхнего уровня проекта. Это где кто-то, кто новичок в вашем проекте начнет. Службы размещения кода, такие как GitHub, Bitbucket и GitLab, также будут искать ваш файл README и отображать его вместе со списком файлов и каталогов в вашем проекте.

Как мне это сделать?

Несмотря на то, что файлы README могут быть записаны в любом текстовом формате, наиболее распространенным в настоящее время является формат Markdown. Это позволяет вам добавить легкое форматирование. Вы можете узнать больше об этом на веб-сайте CommonMark, где также есть полезное справочное руководство и интерактивный учебник.

Некоторые другие форматы, которые вы можете встретить, – это обычный текст, reStructuredText (распространенный в проектах Python) и Textile.

Вы можете использовать любой текстовый редактор. Существуют плагины для многих редакторов (например, Atom, Emacs, Sublime Text, Vim и Visual Studio Code), которые позволяют вам предварительно просматривать Markdown во время редактирования.

Вы также можете использовать специальный редактор Markdown, например Typora, или онлайн-редактор, например StackEdit или Dillinger. Вы даже можете использовать редактируемый шаблон ниже.

Шаблон

Ввод уценки (редактируемый)

Foobar — это библиотека Python для работы со множественным числом слов.

Установка

Используйте pip менеджера пакетов для установки foobar.

Использование

Содействие

Запросы на вытягивание приветствуются. В случае серьезных изменений сначала откройте вопрос, чтобы обсудить, что вы хотели бы изменить.

Не забудьте обновить тесты соответствующим образом.

Лицензия

Предложения по хорошему файлу README

Каждый проект уникален, поэтому подумайте, какие из этих разделов относятся к вашему. Разделы, используемые в шаблоне, являются рекомендациями для большинства проектов с открытым исходным кодом. Также имейте в виду, что хотя README может быть слишком длинным и подробным, лучше слишком длинный, чем слишком короткий. Если вы считаете, что README слишком длинный, рассмотрите возможность использования другой формы документации, а не вырезания информации.

Выберите понятное название для вашего проекта.

Описание

Сообщите людям, что конкретно может сделать ваш проект. Предоставьте контекст и добавьте ссылку на любую ссылку, с которой посетители могут быть незнакомы. Здесь также можно добавить список функций или подраздел «Фон». Если у вашего проекта есть альтернативы, это хорошее место, чтобы перечислить отличительные факторы.

Значки

В некоторых файлах README вы можете увидеть небольшие изображения, передающие метаданные, например, все ли тесты проекта пройдены. Вы можете использовать Shields, чтобы добавить некоторые из них в свой README. Во многих службах также есть инструкции по добавлению значка.

Визуальные эффекты

В зависимости от того, что вы делаете, может быть хорошей идеей включить скриншоты или даже видео (часто вы будете видеть GIF-файлы, а не настоящие видео). Такие инструменты, как ttygif, могут помочь, но попробуйте Asciinema для более сложного метода.

Установка

В рамках определенной экосистемы может существовать общий способ установки, например с помощью Yarn, NuGet или Homebrew. Однако учтите возможность того, что тот, кто читает ваш README, является новичком и хотел бы получить дополнительные указания.Перечисление конкретных шагов помогает устранить двусмысленность и побуждает людей использовать ваш проект как можно быстрее. Если он работает только в определенном контексте, таком как конкретная версия языка программирования или операционная система, или имеет зависимости, которые необходимо установить вручную, также добавьте подраздел «Требования».

Использование

Широко используйте примеры и покажите ожидаемый результат, если можете. Полезно иметь встроенный наименьший пример использования, который вы можете продемонстрировать, предоставляя ссылки на более сложные примеры, если они слишком длинны для включения в README.

Поддержка

Сообщите людям, куда они могут обратиться за помощью. Это может быть любая комбинация системы отслеживания проблем, чата, адреса электронной почты и т. д.

Дорожная карта

Если у вас есть идеи для выпусков в будущем, рекомендуется перечислить их в файле README.

Содействие

Укажите, открыты ли вы для пожертвований и каковы ваши требования для их принятия.

Для людей, которые хотят внести изменения в ваш проект, будет полезно иметь некоторую документацию о том, как начать работу. Возможно, есть сценарий, который они должны запустить, или какие-то переменные среды, которые им нужно установить. Сделайте эти шаги явными. Эти инструкции также могут быть полезны вам в будущем.

Вы также можете задокументировать команды для анализа кода или запуска тестов. Эти шаги помогают обеспечить высокое качество кода и снизить вероятность того, что изменения непреднамеренно сломают что-то. Инструкции по запуску тестов особенно полезны, если для этого требуется внешняя настройка, например запуск сервера Selenium для тестирования в браузере.

Авторы и благодарность

Выразите признательность тем, кто внес свой вклад в проект.

Лицензия

Для проектов с открытым исходным кодом укажите, как они лицензируются.

Статус проекта

Если у вас закончились энергия или время для вашего проекта, поместите примечание вверху файла README о том, что разработка замедлилась или полностью остановилась. Кто-то может решить разветвить ваш проект или добровольно выступить в качестве сопровождающего или владельца, что позволит вашему проекту продолжать работу. Вы также можете сделать явный запрос на сопровождающих.

Есть ли стандартный формат README?

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

Что еще вы думаете о написании README?

Ознакомьтесь со списком дополнительных ресурсов в Awesome README.

Как должен называться файл README?

README.md (или другое расширение файла, если вы решите использовать формат файла, отличный от Markdown). Традиционно оно пишется прописными буквами, чтобы быть более заметным, но это не имеет большого значения, если вы считаете, что строчные буквы выглядят лучше.

Что делать, если я с чем-то не согласен, хочу внести изменения или хочу оставить отзыв?

Пожалуйста, не стесняйтесь открывать тикеты или пулреквесты. Вы также можете отправить мне сообщение в Twitter.

Чтение мыслей?

Ученые и такие компании, как Facebook и Neuralink (предположительно), работают над этим. Возможно, в будущем вы сможете прикреплять к своим проектам копию своих мыслей и/или сознания. А пока сделайте README.

Что дальше?

Лицензия

Если ваш проект с открытым исходным кодом, важно включить лицензию. Вы можете использовать этот веб-сайт, чтобы помочь вам выбрать один.

Журнал изменений

Создать README вдохновлен Keep a Changelog. Журнал изменений — это еще один файл, очень полезный для проектов программирования.

Дополнительная документация

README — это важный, но основной способ документирования вашего проекта. В то время как у каждого проекта должен быть как минимум README, более активные могут также извлечь пользу из вики или специального веб-сайта с документацией. GitHub, Bitbucket и GitLab поддерживают поддержку вики параллельно с вашим проектом, и вот несколько инструментов и сервисов, которые помогут вам создать веб-сайт с документацией:

Содействие

Хорошим началом будет наличие раздела "Содействие" в вашем файле README. Другой подход — выделить ваши рекомендации в отдельный файл (CONTRIBUTING.md). Если вы используете GitHub и у вас есть этот файл, то любой, кто создаст задачу или откроет запрос на вытягивание, получит ссылку на него.

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

Make a README поддерживается Дэнни Гуо, размещается на GitHub с лицензией MIT и поддерживается Netlify.

Читайте также: