Github wiki как работать

Практическое занятие: Управляем контентом в Wiki Github

На этом занятии мы рассмотрим процесс публикации на одной из самых распространенных платформ для разработчиков: GitHub. Созданный репозиторий на GitHub имеет свою Wiki, к которой можно добавлять страницы. Wiki удобна, если исходный код хранится на GitHub. Хотя GitHub может и не быть платформой, на которой мы будем публиковать свою документацию, понимание того, как работать с этой платформой важно для понимания контроля версий.

Изучение GitHub позволит ознакомиться с рабочими процессами управления версиями, которые являются общими для многих инструментов docs-as-code. По этой причине на этом курсе есть подробное руководство по использованию GitHub. Независимо от того, используется GitHub в качестве инструмента публикации, это руководство познакомит с рабочими процессами работы Git с контентом.

О Wiki на GitHub

Wii на GitHub можно использовать в качестве сайта документации. Вот пример API Basecamp, который размещен на GitHub.

В отличие от других Wiki, создаваемый Wiki на GitHub — это собственный репозиторий, который можно клонировать и работать локально. (Если посмотреть на ссылку «Клонировать эту Wiki локально», то увидим, что это хранилище, отдельное от основного хранилища кода.) С файлами можно работать локально, и фиксировать их в хранилище Wiki. Можно расположить ссылки на вики-страницы на боковой панели.

Wiki-страницы на GitHub используют синтаксис Markdown. Для этого есть специальная версия, названная Github-flavored Markdown или GFM. Эта версия Markdown позволяет создавать таблицы, классы для блоков кода (для корректной подсветки синтаксиса) и т.д.

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

Warning: Git используется только для отслеживания текстовых файлов. Не работает Git c большими двоичными файлами, такими как аудиофайлы, видеофайлы, файлы Microsoft Word или файлы Adobe PDF. Системы контроля версий действительно не справляются с такими форматами, и размер репозитория будет возрастать в геометрической прогрессии. Используя Git для управления документацией, такие файлы исключаются через файл .gitignore. Можно также исключить изображения, так как они увеличивают размер вашего репо.

Ограничения wiki на GitHub

Github имеет некоторые ограничения:

• ограниченный дизайн: все Wiki GitHub в значительной степени выглядят одинаково;
• открытый доступ в Интернете: если документация должна быть приватной, GitHub вряд ли будет подходящим местом для хранения (однако, есть опция делать репозитории приватными);
• нет структуры: Вики-страницы GitHub выдают пустую страницу и позволяют добавлять разделы. Но нет возможности делать какие-либо продвинутые стили или интерактивные функции.

Note: Здесь речь именно о встроенной функции Wiki на GitHub, а не GitHub Pages. Для стилизования и автоматического создания контента можно использовать такие инструменты, как Jekyll. Более подробно GitHub Pages рассмотрим в руководстве по Jekyll.

Установка Git

Прежде чем начать работать с GitHub нужно настроить Git и установить все необходимые инструменты и учетные данные для работы с GitHub (особенно если вы работаете в Windows).

Установка на Mac

Установка Git на Mac: Installing on Mac

После установки можно пользоваться Git несколькими вариантами:

• в предустановленном терминале, выбрав Applications > Utilities > Terminal;
• установить сторонний терминал iTerm;
• использовать PlatformIO IDE Terminal в Atom (наверное самый удобный способ работы с проектами)

Установка на Windows

Самый подходящий установщик для Windows это Git for Windows

Этот инсталлятор включает в себя эмулятор терминала Git BASH, который позволят использовать команды Git и Unix.

Проверить, установлен ли у вас Git, открыв терминал и введя следующее:

git --version 

Настройка автоматической аутентификации GitHub

Git можно настроить так, чтобы не приходилось каждый раз вводить имя пользователя и пароль каждый раз при внесении изменений в GitHub. Как настроить можно почитать по ссылкам:

• Set up Git
• Generating a new SSH key and adding it to the ssh-agent
• Adding a new SSH key to your GitHub account
• Associating text editors with Git

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

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

��‍�� Практическое занятие: Создаем Wiki на GitHub и публикуем пример страницы

Создаем wiki на GitHub и публикуем контент на пробной странице

В этом упражнении создадим новый репозиторий на сайте GitHub и опубликуем файла.

• Открываем GitHub и логинимся там. После нажимаем кнопку + и выбираем New repository

• Вписываем имя репозитория, краткое описание, выбираем видимость public , выбираем Initialize the repo with a README и затем нажимаем Create repository (Не стоит обращать внимания на выбор лицензии настроек gitignore для этого упражнения).
• Переходим на вкладку Wiki в навигационной панели нового репозитория.
• Нажимаем кнопку Create the first page (Если wiki уже существует, то нажимаем New Page ).
• На начальной странице Home вставляем свой документ, предпочтительно написанный в Markdown. Или можно просто перетащить содержимое страницы fake endpoint called surfreport here.
• В поле Edit message вписываем краткое описание (коммит).
• Нажимаем Save Page

Обратите внимание, как GitHub автоматически преобразует синтаксис Markdown в HTML и стилизует его для удобства чтения.

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

��‍�� Практическое занятие: Делаем локальную копию репозитория

Клонируем репозиторий на локальную машину

До сих пор мы работали с GitHub в браузере. Теперь мы возьмем тот же контент и будем работать с ним локально. Это то, что делает вики GitHub уникальным среди других вики — это репозиторий Git, поэтому вы можете управлять контентом так же, как и любым другим репозиторием Git (работая локально, выдвигая, вытягивая, объединяя, разветвляя и т. Д.).

• Если на компьютере до сих пор не установлен клиент Git, тогда самое время его установить. (Проверить установку можно командой git —version в командной строке. Подробно об установке Gitвыше).
• Просматривая вики-страницу GitHub в своем браузере, обратим внимание на раздел Clone this wiki locally . Нажмите кнопку буфера обмена. (Копируется URL клона в ваш буфер обмена.)

Note: Вики имеет отдельный URL, не относящийся к репозиторию проекта. Убедитесь, что вы просматриваете вики, а не проект. URL клона будет включать .wiki.

В отличие от раздела Clone this wiki locally , кнопка «Clone in Desktop» запускает клиент GitHub Desktop и позволяет управлять репозиторием и вашими измененными файлами, фиксировать, передавать и извлекать через клиент GitHub Desktop. Об этом написано в практическом занятии Используем клиент GitHub для десктопа

• Открываем командную строку
  • те кто пользуется Windows, открывают эмулятор терминала Git Bash,
  • пользователи MacOS запускают Applications > Utilities > Terminal или iTerm

  git clone https://github.com/tomjoht/weatherapi.wiki.git 

  Нажимаем Enter и ждем пока система клонирует wiki. В это время видим на экране исполнение команды:

  Cloning into 'weatherapi.wiki'. remote: Enumerating objects: 3, done. remote: Counting objects: 100% (3/3), done. remote: Compressing objects: 100% (2/2), done. remote: Total 9 (delta 0), reused 0 (delta 0), pack-reused 6 Unpacking objects: 100% (9/9), done. 

  В примере Git создал папку weatherapi.wiki

  Клонирование вики делает копию содержимого на вашем локальном компьютере. Git — это программное обеспечение для контроля версий, поэтому у каждого есть своя собственная копия. Когда вы клонируете репозиторий, вы создаете копию на своем локальном компьютере; версия в облаке на GitHub называется «origin». Таким образом, у вас есть два экземпляра контента.

  Однако, когда вы клонируете репозиторий, вы не просто копируете файлы, а инициализируете Git в папке, куда сохранен репозиторий. Инициализация Git означает, что Git создаст невидимую папку Git в этом каталоге, и Git может начать отслеживать ваши изменения в файлах, обеспечивая контроль версий. С инициализацией Git вы можете запускать команды pull , чтобы получать обновления из онлайн-хранилища (источника) в локальную копию. Вы также можете фиксировать commit свои изменения и затем вернуть их «origin».

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

  Tip: Необязательно вводить полное имя каталога. Просто начните вводить первые несколько букв, а затем нажмите клавишу Tab , чтобы автоматически ввести полное имя.

  ��‍�� Практическое занятие: Отправляем локальные изменения в удаленный репозиторий

  Отправляем локальные изменения на удаленный репозиторий

  • В текстовом редакторе открываем наш файл, скачанный с репозитория git Hub. Файл будет открыт в приложении по умолчанию, связанном с этим типом файла. Вы также можете открыть файл, перейдя к нему вручную и открыв его, как обычно (просмотр в Finder или Explorer).
  • Внесем изменения и сохраним файл. Например напишем свое имя вверху документа.
  • В терминале удостоверимся, что находимся в нужной папке.

  Для просмотра впишем команду ls под текущей строкой. Потом введем команду сd/ для входа в папку или cd ../ для перемещения на уровень выше.

  • Добавим все файлы:

  git add . 

  Git не отслеживает все файлы в той папке, где он был инициализирован. Git отслеживает изменения только для файлов, которые были «добавлены» в Git. Набрав git add . или git add —all , вы говорите Git начать отслеживать изменения всех файлов в этом каталоге. Вместо этого вы также можете ввести здесь определенное имя файла, например git add Home.md , чтобы просто добавить определенный файл (а не все файлы, которые были изменены) для отслеживания в Git.

  После команды git add Git добавляет файлы в так называемую область подготовки. Используя спортивную аналогию, площадка для постановки похожа на беговую дорожку. Эти файлы готовы для фиксации, когда вы запускаете git commit .

  • Просмотреть статус файла можно командой

  git status 

  Git ответит сообщением, указывающим, какие файлы готовы для коммита.

  Changes to be committed: (use "git reset HEAD . " to unstage) modified: Home.md 

  В области подготовки перечислены все файлы, которые были добавлены в Git и которые вы каким-либо образом изменили.

  Рекомендуется всегда проверять git status перед фиксацией файлов, потому что вы можете понять, что, набрав git add . , Вы могли случайно добавить некоторые файлы, которые вы не собирались отслеживать (например, большие двоичные файлы). Если вы хотите удалить этот файл из промежуточной области, вы можете ввести команду git reset HEAD Home.md , чтобы удалить его.

  • Коммитим изменения

  git commit -m "updated some content" 

  Коммит создает слепок файла в данный момент времени для версионирования.

  Команда git commit -m является ярлыком для фиксации и ввода сообщения коммита. Обновления таким способом гораздо проще фиксировать.

  Если ввести только git commit, то будет предложено ввести описание коммита в режиме редактора Bash. Опишите изменения в верхней строке, а затем сохраните и закройте окно.

  На Mac новое окно не открывается. Вместо этого в терминале открывается режим редактора Vim. («Vi» обозначает visual, а «m» — режим, но это не очень визуальный редактор.) Для выхода из редактора нажимаем клавишу Escape. Затем вводим q , чтобы выйти. (См. Здесь команды Vim.) Возможно захочется настроить терминал так, чтобы открывался внешний редактор, такой как Sublime Text. Подробности в разделе Связывание текстовых редакторов с Git.

  • Отправляем изменения на удаленный репозиторий командой

  git push 

  Если автоматическая аутентификация на GitHub не настроена, то будет предложено ввести ваши учетные данные: логин и пароль (Ваш username — это логин ID на GitHub).

  Обратите внимание: когда вы набираете git push или git pull и не указываете ветку, GitHub использует ветку по умолчанию из источника. Ветвь по умолчанию на GitHub называется master . Таким образом, фактически переданная команда — это git push origin master (это означает: отправить эти изменения в удаленный репозиторий origin, в ветке master). Некоторые разработчики предпочитают указывать хранилище и ветвь, чтобы обеспечить взаимодействие с нужными хранилищами и ветвями.

  Окно терминала на Mac, будет выглядеть примерно так:

  

  • Теперь проверим наши изменения. Заходим на удаленный репозиторий и посмотрим изменения.

  Предотвращение конфликтов слияния при редактировании онлайн и локально

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

  Сведения о вики-сайтах

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

  Wikis are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see «GitHub’s plans.»

  Every repository on GitHub.com comes equipped with a section for hosting documentation, called a wiki. You can use your repository’s wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles. A README file quickly tells what your project can do, while you can use a wiki to provide additional documentation. For more information, see «About READMEs.»

  With wikis, you can write content just like everywhere else on GitHub. For more information, see «Getting started with writing and formatting on GitHub.» We use our open-source Markup library to convert different formats into HTML, so you can choose to write in Markdown or any other supported format.

  You can use Markdown to add rendered math expressions, diagrams, maps, and 3D models to your wiki. For more information on creating rendered math expressions, see «Writing mathematical expressions.» For more information on creating diagrams, maps and 3D models, see «Creating diagrams.»

  If you create a wiki in a public repository, the wiki is available to the public. If you create a wiki in a private repository, only people with access to the repository can access the wiki. For more information, see «Setting repository visibility.»

  You can edit wikis directly on GitHub, or you can edit wiki files locally. By default, only people with write access to your repository can make changes to wikis, although you can allow everyone on GitHub.com to contribute to a wiki in a public repository. For more information, see «Changing access permissions for wikis.»

  Note: Search engines will only index wikis with 500 or more stars that you configure to prevent public editing. For more information, see «Changing access permissions for wikis.»

  If you need search engines to index your content, you can use GitHub Pages in a public repository.

  Further reading

  • «Adding or editing wiki pages»
  • «Creating a footer or sidebar for your wiki»
  • «Editing wiki content»
  • «Viewing a wiki’s history of changes»
  • «Searching wikis»

  Добавление и редактирование вики-страниц

  Вы можете добавлять и изменять страницы вики-сайта непосредственно в GitHub или локально с помощью командной строки.

  Wikis are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see «GitHub’s plans.»

  Adding wiki pages

  1. On GitHub.com, navigate to the main page of the repository.
  2. Under your repository name, click

  

  Wiki.

  

• In the upper-right corner of the page, click New Page.
• Optionally, to write in a format other than Markdown, use the «Edit mode» dropdown to choose a different format.

  Editing wiki pages

  1. On GitHub.com, navigate to the main page of the repository.
  2. Under your repository name, click

  

  Wiki.

  Adding or editing wiki pages locally

  Wikis are part of Git repositories, so you can make changes locally and push them to your repository using a Git workflow.

  Cloning wikis to your computer

  Every wiki provides an easy way to clone its contents down to your computer. Once you’ve created an initial page on GitHub, you can clone the repository to your computer with the provided URL:

  $ git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.wiki.git # Clones the wiki locally 

  Once you have cloned the wiki, you can add new files, edit existing ones, and commit your changes. You and your collaborators can create branches when working on wikis, but only changes pushed to the default branch will be made live and available to your readers.

  About wiki filenames

  The filename determines the title of your wiki page, and the file extension determines how your wiki content is rendered.

  Wikis use our open-source Markup library to convert the markup, and it determines which converter to use by a file’s extension. For example, if you name a file foo.md or foo.markdown, wiki will use the Markdown converter, while a file named foo.textile will use the Textile converter.

  Don’t use the following characters in your wiki page’s titles: \ / : * ? » < >| . Users on certain operating systems won’t be able to work with filenames containing these characters. Be sure to write your content using a markup language that matches the extension, or your content won’t render properly.

  Организация информации с помощью таблиц

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

  Создание таблицы

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

   | First Header | Second Header | | ------------- | ------------- | | Content Cell | Content Cell | | Content Cell | Content Cell | 

  

  Вертикальные черты на обоих концах таблицы не являются обязательными.

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

  | Command | Description | | --- | --- | | git status | List all new or modified files | | git diff | Show file differences that haven't been staged | 

  

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

  Форматирование содержимого в таблице

  В таблице можно использовать форматирование, например ссылки, встроенные блоки кода и оформление текста:

  | Command | Description | | --- | --- | | `git status` | List all *new or modified* files | | `git diff` | Show file differences that **haven't been** staged | 

  

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

  | Left-aligned | Center-aligned | Right-aligned | | :--- | :---: | ---: | | git status | git status | git status | | git diff | git diff | git diff | 

  

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

  | Name | Character | | --- | --- | | Backtick | ` | | Pipe | \| | 

  

  Дополнительные материалы

  • Спецификация GitHub Flavored Markdown
  • «Базовый синтаксис записи и форматирования»
  Похожие публикации:

  1. Request url что это
  2. Как добавить фото в вк
  3. Как посчитать премию в excel
  4. Как удалить игры из рокстар геймс