Word до GitHub Markdown: Форматировать документы для GitHub READMEs и проблем

GitHub использует Markdown диалект, называемый GitHub Ароматизированные Markdown (GFM). It’s mostly standard Markdown with a few extras — fenced code blocks with syntax highlighting, task lists, tables, and automatic link detection. If you’re converting a Word document into a GitHub README or wiki page, here’s what you need to know.

Что такое GitHub с ароматом Markdown?

GFM является GitHubs расширение CommonMark. Добавления, которые имеют наибольшее значение при преобразовании из Word, следующие:

• Огражденные блоки кода с языковыми идентификаторами (```python)
• Таблицы Использование синтаксиса трубки
• Списки задач using - [ ] and - [x]
• Прохождение using ~~text~~
• Автоссылки Голые URL-адреса становятся доступными для нажатия

Преобразовать ваш Word документ на WordToMD и вы получите GFM-совместимый выход по умолчанию.

Word Стили → GFM Элементы

GitHub-Специфические функции, которые должны быть добавлены после преобразования

Списки задач

Word не имеет элемента списка задач. Если в Word doc есть выберительные окна, они преобразуются в простой текст. После преобразования форматируйте их как GFM списки задач:

- [x] Completed item
- [ ] Pending item
- [ ] Another pending item

Они отображаются как интерактивные окна для отметки в файлах GitHub Issues, Pull Requests и project README.

Огражденные блоки кода с выделением синтаксиса

Текст монопространства из Word преобразуется в встроенный код. Для многостроковых блоков кода на GitHub, используйте скрещенный синтаксис с идентификатором языка:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

GitHub supports dozens of languages. See [Markdown Code Blocks Guide](/blog/markdown-code-blocks-guide) for the full language list and syntax rules.

### Alerts (GitHub-Specific Callouts)

GitHub renders special blockquote syntax as colored callout boxes:

```markdown
> [!NOTE]
> This is a note callout.

> [!WARNING]
> This is a warning.

> [!TIP]
> This is a helpful tip.

Если в вашем документе Word есть ящики для вызова или выделенные заметки, преобразуйте их в синтаксис GFM после первоначальной конвертации.

Структурирование README из Word документа

Типичное программное обеспечение README имеет следующую структуру:

# Project Name

Short description.

## Installation

## Usage

## Configuration

## Contributing

## License

Если ваш Word документ является спецификацией проекта или проектом документации, сопоставьте его разделы с этими README заголовками. Использование WordToMD преобразовать сырьевое содержимое, а затем реорганизовать и добавить GitHub-специфические элементы.

Таблицы в GitHub Markdown

Word таблицы преобразуются непосредственно в GFM таблицы труб. Вот как выглядит преобразованная таблица:

| Feature | Status | Notes |
|---|---|---|
| Authentication | ✅ Done | JWT-based |
| File upload | 🚧 In progress | S3 target |
| API docs | ❌ Pending | — |

GitHub также поддерживает выравнивание столбцов:

| Left | Center | Right |
|:---|:---:|---:|
| text | text | text |

Все о таблицах Markdown см. Markdown Таблицы: полное руководство.

Изображения в GitHub репозиториях

GitHub отображает изображения из относительных путей в репо:

![Architecture diagram](docs/images/architecture.png)

Если Word документ содержит поддерживаемые изображения, скачать Markdown + изображения ZIP, переместить упакованные файлы изображения в docs/images/, и обновлять относительные пути, если ваш репозиторий использует другую структуру папок.

Для изображений, размещенных в GitHub.com, вы также можете использовать абсолютные URL-адреса:

![Screenshot](https://github.com/user/repo/raw/main/screenshot.png)

GitHub Страницы Вики

GitHub вики поддерживает полную спецификацию GFM. Рабочий процесс преобразования такой же, как и для README:

1. Преобразовать документ Word с помощью WordToMD
2. Добавить GFM-специфическое форматирование (списки задач, кодовые ограждения, оповещения)
3. Создайте новую страницу вики и вставьте Markdown

Идентификаторы заголовков и якорные ссылки

GitHub автоматически генерирует идентификаторы якорей из текста заголовка. Рубрика ## Installation получает удостоверение личности #installation. You can link to it from elsewhere in the same document:

See the [Installation section](#installation) below.

Это полезно для длинных README с таблицей содержимого. После преобразования вверху добавить TOC:

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)

FAQ

Является ли GitHub представлением HTML в Markdown? GitHub позволяет использовать некоторые теги HTML в Markdown, но устраняет большинство стилевых атрибутов. Следите за синтаксисом Markdown для достижения наилучших результатов.

У меня слишком много столбцов, и на мобильном выглядит тесно. Что мне делать? Подумайте о том, чтобы разбить большие таблицы на более мелкие, сфокусированные, или использовать HTML <details> маркировки для складывающихся частей.

Могу ли я использовать Word для написания GitHub вопросов? - Да, я знаю. Преобразовать ваш Word doc в Markdown с WordToMD и вставьте выход непосредственно в описание GitHub Issue или Pull Request.

Как я могу преобразовать весь набор документов Word в вики GitHub? Конвертируйте каждый Word файл отдельно и создавайте одну страницу вики на документ. См. также: Перевод партии Word на Markdown за написание этого с Pandoc.

Заключение

Преобразование Word в Я не знаю, что это значит. простой использовать WordToMD чтобы получить базу Markdown, затем слой на GFM-специфические функции, такие как списки задач, кодовые ограждения и оповещения о вызове. С чистой структурой в вашем Word документе (встроенные стили заголовков, соответствующие таблицы), вывод преобразования будет почти готов к переходу на GitHub.