Практическое занятие: Управляем контентом в 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 statusGit ответит сообщением, указывающим, какие файлы готовы для коммита.
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 . Если два человека одновременно редактируют один и тот же контент между коммитами, вероятно, потребуется разрешить конфликты слияния.
Github + Markdown = Viewdocs
Для ПО с открытым исходным кодом очень большое значение имеет документация. На своем опыте я убедился, что написание хорошей документации зачастую даже важнее написания тестов.
Когда я перерос README на Github, я рассматривал только 2 варианта для документации: Github Pages и Read the Docs. К сожалению, у меня возникли проблемы с обоими. Главным образом, Read the Docs заставляет меня использовать reStructured Text, а Github Pages подразумевает поддержку отдельной ветки и использование генератора статичных страниц.
На самом деле, я бы хотел иметь нечто похожее на Gist.io, только для моего репозитория. Не найдя ничего подходящего, я написал это сам.
Я называю это Viewdocs. Сервис на лету создает страницы из markdown в папке docs Вашего проекта. Установка не требуется, просто следуйте соглашениям. Возможно для Вас это уже работает, т.к. markdown в папке docs — не такая уж редкость.
Шаблон, используемый по-умолчанию, был позаимствован у Gist.io.
Узнать больше Вы можете на сайте Viewdocs, который работает на базе Viewdocs. Или вот небольшой скринкаст-введение:
- Веб-разработка
- Open source
12 потрясающих возможностей GitHub
Поскольку термины Git и другие программистские словечки чаще всего употребляются без перевода, то я решил их не переводить. Приведу их тут, для порядка, краткий перевод терминов из этой статьи с «расшифровкой».
Fork – «развилка». По сути вы копируете себе проект, чтобы на его основе что-то доработать
Pull request — запрос на изменение. Отправка внесенных вами изменений в репозиторий на проверку (то есть в основной проект этот код будет внесен только после подтверждения владельцем репозитория или коллегами по работе)
Pull – «втянуть» (в IDE на вашем компьютере, например) проект с GitHub
Push – «вытолкнуть» проект c локальной машины на GitHub
#1 Редактирование кода на GitHub.com
Начну с того, что, как мне кажется, и так всем известно (хотя лично я и не подозревал об этом еще неделю назад). При просмотре любого текстового файла на сайте GitHub, в любом репозитории, справа сверху можно видеть маленький карандашик. Если щёлкнуть по нему, можно будет отредактировать этот файл. По завершении, нажмите Propose file change («Предложить изменение файла») и GitHub создаст разветвление репозитория (fork) и запрос на внесение изменений (Pull Request). Поразительно, не правда ли? Он сам создает fork! Нет нужды делать форк и загружать к себе код, вносить локально изменения и отправлять обратно на GitHub c Pull Request’ом. Очень удобно, если нужно внести минимальные правки.
не совсем настоящий Pull Request
#2 Вставка изображений
Описания проблем не ограничиваются только текстовыми комментариями. Знаете ли вы, что можно вставлять изображения прямо из буфера обмена? При вставке вы увидите, его загрузку (несомненно, в «облако») и превращение в разметку для отображения изображения. Изящно!
#3 Форматирование кода
Если вам нужно написать блок кода, начните с трёх обратных одинарных кавычек — и GitHub попытается угадать, на каком языке программирования вы пишете. Но если вы размещаете фрагмент кода на таких языках программирования, как Vue, Typescript или JSX, то можете явным образом указать язык, чтобы подсветка синтаксиса была правильной. Обратите внимание на «`jsx в первой строке:
. обеспечивающий правильное отображение фрагмента кода:
(это распространяется и на Gist, кстати. Если указать для гиста расширение .jsf, будет подсвечиваться синтаксис JSF). Вот список всех поддерживаемых синтаксисов.
#4 Закрытие проблем при помощи «магических слов» в Pull Request’ах
Допустим, вы создаете Pull Request, исправляющий проблему #234. Вы можете вставить текст «исправляет проблему #234» в описание вашего запроса (или в любом месте любого комментария к запросу на изменение). После этого слияние Pull Request’а «автомагически» закроет проблему. Круто, не так ли? Вот больше информации об этом в документации.
#5 Ссылка на комментарии
Требовалось ли вам когда-нибудь создать ссылку на конкретный комментарий, а вы не знали, как это сделать? Эти дни давно прошли, поскольку я раскрою вам секрет: для создания ссылки на комментарий нужно просто щелкнуть на дате/времени рядом с названием.
Смотрите, у gaearon’а теперь есть фотка!
#6 Ссылка на код
Итак, вы хотите создать ссылку на конкретную строку кода. В таком случае, попробуйте следующее: щелкните на номере строки рядом с нужным кодом в открытом файле. Ух ты, видите? URL поменялся, в нём теперь виден номер строки! Если удерживать нажатой клавишу SHIFT и нажать на номер другой строки, то – вуаля! – URL поменяется еще раз, и будет подсвечен диапазон строк. Этот URL теперь будет указывать на данный файл и данный диапазон строк. Но погодите, он указывает на текущую ветку. А что, если файл поменяется? Наверное, вам нужна, в этом случае, постоянная ссылка на файл в его текущем состоянии. Я очень ленивый, так что сделал один снимок экрана для всего вышеописанного:
Кстати, насчет URL’ов.
#7 Использование URL GitHub в качестве командной строки
Перемещение по GitHub с помощью UI организовано очень удобно. Но иногда, чтобы попасть в определенное место, быстрее окажется просто набрать его в URL. Например, если мне нужно перейти в ветку, над которой я работаю и посмотреть отличия её от ветки master, я могу просто ввести /compare/имя_ветки после имени репозитория. После этого я попаду на страницу различий для данной ветки:
Но это отличия от ветки master, если же я работал до этого с веткой интеграции, то могу ввести в URL /compare/integration-branch. my-branch
Для любителей горячих клавиш: CTRL+L или CMD+L переводит курсор в строку URL (по крайней мере в браузерах Chrome и Firefox). Это, в сочетании с автодополнением браузера, значительно упрощает перемещение между ветками. Совет от профи: воспользуйтесь стрелками для перемещения по предложениям автодополнения Chrome и нажимайте SHIFT+DELETE для удаления элементов из истории (например, после слияния ветки). (Не знаю, будет ли легче читать эти горячие сочетания клавиш, если буду ставить в них пробел, вот так SHIFT + DELETE. Но формально «+» не является их частью, так что мне этот вариант не нравится. Именно из-за таких вещей я и не сплю по ночам, Ронда.)
#8 Создание списков для проблем
Хотите ли вы, чтобы в вашем описании проблемы присутствовал чекбокс?
И хотите ли вы, чтобы при просмотре проблемы из списка отображалась элегантная полоска вроде «2 из 5»?
- [ ] Screen width (integer)
- [x] Service worker support
- [x] Fetch support
- [ ] CSS flexbox support
- [ ] Custom elements
Если вам непонятно, что я имею в виду под «панелью проекта» – читайте ниже. Всего на пару сантиметров ниже на этой странице.
#9 Панели проектов в GitHub
Для больших проектов я всегда использовал Jira. А для своих личных проектов я всегда использовал Trello. Оба этих инструмента мне очень нравятся. Когда несколько недель назад я узнал, что GitHub предлагает свой собственный вариант, прямо на закладке Projects репозитория, я подумал, что иметь смысл продублировать набор задач, с которыми я уже работаю в Trello.
Ничего веселого тут нет А теперь то же самое в проекте GitHub:
Постепенно ваши глаза привыкнут к неконтрастному изображению Ради ускорения я добавил все вышеуказанное в виде заметок (notes), то есть они не являются «настоящими» проблемами (issues) GitHub. Но мощь управления задачами в GitHub состоит в интеграции с остальным репозиторием – так что, вероятно, лучше добавить существующие проблемы из репозитория на панель. Нажмите Add Cards в верхнем правом углу и найдите то, что хотели бы добавить. Здесь пригодится специальный синтаксис поиска: например, наберите is:pr is:open и вы сможете перетащить любой открытый Pull Request на панель, или label:bug, если нужно исправить какие-то ошибки.
А ещё можно преобразовать существующие заметки в проблемы.
И, наконец, из формы существующей проблемы, добавить её в проект в правой панели.
Она попадёт в список triage данной панели проекта, так что вы сможете выбрать, в какой столбец её поместить Когда описание «таска» находится в том же репозитории, что и реализующий этот таск код, это очень (ооооочень) удобно. Это значит, что через много лет вы сможете выполнить команду git blame для какой-либо строки кода и выяснить всю подоплёку задачи, которая к этой строке привела, без того, чтобы отслеживать это всё в Jira/Trello/еще где-нибудь.
Недостатки
Последние три недели я экспериментировал с выполнением всех задач в GitHub вместо Jira (на маленьком проекте, примерно в стиле Канбан) и мне это понравилось. Но я не могу себе представить это для scrum-проекта, где необходимо оценивать и подсчитывать должным образом скорость разработки и тому подобное. Хорошая новость: у проектов GitHub настолько мало «особенностей», что переход на другую систему не займет, в случае чего, много времени. Так что попробуйте, посмотрим, насколько вам понравится. Не знаю, насколько это важно, но я слышал про ZenHub и открыл его впервые 10 минут назад. Фактически это расширение GitHub, в котором можно оценивать проблемы и создавать «epics» и зависимости. Там есть графики скорости разработки и выгорания; похоже, что это просто потрясающая вещь. Дальнейшее чтение: документация GitHub по Projects.
#10 Gwiki
Для неструктурированного набора страниц – подобного Википедии – GitHub Wiki (которую я буду далее называть просто Gwiki) просто великолепна. Для структурированного же набора страниц – например, как ваша документация – уже не настолько. Отсутствует возможность указать, что «вот эта страница – дочерняя по отношению к вот той», нет таких удобных вещей, как кнопки «Следующий раздел» и «Предыдущий раздел». Гензель и Гретель тут бы точно заблудились, потому что «хлебных крошек» (специальных отладочных операторов – прим. перев.) тут тоже нет. (Примечание автора: Вы читали эту историю? Она просто бесчеловечна. Двое юных отморозков убивают несчастную голодную старушку, сжигая её заживо в её собственной печи. И конечно же, оставляя непонятно кому полный беспорядок. Мне кажется, именно поэтому молодежь в наши дни адски чувствительна – в наши дни сказки, читаемые детям перед сном, недостаточно жестоки!) Продолжаем – чтобы попробовать Gwiki на деле, я ввел несколько страниц из NodeJS в качестве страниц вики, после чего создал пользовательскую боковую панель, чтобы смоделировать реальную структуру сайта. Эта боковая панель находится там постоянно, хотя текущая страница и не подсвечивается. Ссылки придется поддерживать вручную, но в целом все работает отлично. Если хотите, можете взглянуть:
Это вряд ли может соперничать с чем-то вроде GitBook (который используется в документации Redux) или сделанным на заказ веб-сайтом. Но это уже добрых 80% от него и все прямо в вашем репозитории. Я просто фанат этого. Предлагаю: если вы уже переросли этап использования одного файла README.md и вам нужно несколько различных страниц для руководств пользователя или более подробной документации, имеет смысл остановиться на Gwiki. Если же отсутствие структуры/навигации вам мешает, переходите на что-либо ещё.
#11 GitHub Pages
Возможно, вы уже знали, что GitHub Pages можно использовать для размещения статического сайта. А если не знали, то знаете теперь. Однако этот раздел посвящен более узкому вопросу: использованию Jekyll для создания сайта. В простейшем варианте, GitHub Pages + Jekyll могут визуализировать файл README.md с использованием приятной глазу темы. Например, взгляните на мою страницу readme из about-github:
Если нажать на закладку settings («настройки») для этого сайта на GitHub, включить GitHub Pages и выбрать тему Jekyll.
То мы получим страницу в стиле темы Jekyll:
После этого можно создать целый статический сайт на основе, главным образом, легко редактируемых файлов разметки, по существу, превращая GitHub в CMS. Хотя фактически я этого не использовал, именно так создаются сайты на фреймворке Bootstrap с использованием React, так что ничего ужасного в этом нет. Отмечу, что на локальной машине должен быть запущен Ruby (пользователи Windows тут обменяются понимающими взглядами и пойдут другим путём, пользователи macOS скажут: «В чем проблема, вы куда? Ruby – универсальная платформа! Там же есть система управления пакетами GEMS!») (Стоит отметить также, что «Агрессивный или угрожающий контент или поведение» в GitHub Pages недопустимы, так что вы не сможете разместить там свою версию истории про Гензеля и Гретель).
Мое мнение
Чем детальнее я изучал связку GitHub Pages + Jekyll (для этой статьи), тем больше мне казалось, что вся эта идея странно попахивает. Идея «сделать свой собственный веб-сайт с приложением минимальных усилий» замечательна. Но для работы над ним все равно требуется текущий вариант на локальной машине. И для чего-то столь «простого» тут слишком много команд командной строки. Я бегло просмотрел семь страниц из раздела Getting Started и почувствовал, что единственное, что тут простого – это я сам. И это я еще даже не разобрался с простым синтаксисом для главной страницы или азами простого «Механизма шаблонизации на основе языка Liquid». Уж лучше я напишу веб-сайт самостоятельно! Если честно, я немного удивлен, что Facebook использует это для документации React, в то время как они могли бы, вероятно, формировать страницы их системы помощи при помощи React и выполнять предварительную визуализацию в виде статических HTML-файлов каждый день. Все, что им нужно – всего лишь найти способ получать существующие файлы разметки так, как если бы они поступали из CMS. А что, если.
#12 Использование GitHub в качестве CMS
Допустим, у нас есть веб-сайт с каким-то текстом, но нам не хотелось бы хранить этот текст в виде HTML-разметки. Вместо этого, мы хотели бы хранить где-то куски текста, чтобы их могли легко редактировать и обычные пользователи, не разработчики. Желательно, с каким-то вариантом управления версиями. Возможно, даже с какой-нибудь процедурой рецензирования. Вот что я предлагаю: использовать хранимые в репозитории файлы разметки для хранения текста. И использовать компонент в клиентской части, который бы извлекал эти куски текста и отображал их на странице. Я поклонник React, так что вот пример соответствующего компонента
, который, при заданном пути к файлу разметки, извлечет его, выполнит синтаксический разбор и визуализацию в виде HTML. class Markdown extends React.Component < constructor(props) < super(props); // Конечно, вам нужно заменить это на свой URL this.baseUrl = 'https://raw.githubusercontent.com/davidgilbertson/about-github/master/text-snippets'; this.state = < markdown: '', >; > componentDidMount() < fetch(`$/$`) .then(response => response.text()) .then((markdown) => < this.setState(); >); > render() < return ( > /> ); > >(я использую тут пакет npm marked для синтаксического разбора разметки в HTML) URL указывает на мой репозиторий примеров, в каталоге /text-snippets которого лежат файлы разметки. (Можно также использовать API GitHub для получения контента, но я сомневаюсь, что это вам пригодится) Использовать подобный компонент можно следующим образом:
const Page = () => ();A very important disclaimer:
Так что теперь GitHub играет роль, в некотором роде, вашего CMS, для тех кусков текста, которые вы хотели бы разместить. Вышеприведенный пример извлекает разметку только после того, как компонент будет загружен в браузере. Если вам нужен статический сайт, то придется визуализировать его на сервере. Хорошая новость! Ничто не мешает вам извлечь все файлы разметки на сервере (при использовании любой устраивающей вас стратегии кэширования). Если вы решите пойти этим путем, то вам имеет смысл воспользоваться API GitHub, чтобы получить список всех файлов разметки в каталоге. Бонус – утилиты GitHub! Я уже довольно давно использую расширение Octotree для браузера Chrome и рекомендую его вам. Не без оговорок, но все же рекомендую. Оно отображает слева панель с древовидным представлением просматриваемого репозитория.
А из этого видео я узнал про octobox, который также пока что представляется мне весьма неплохой утилитой. Это папка для входящих для ваших проблем GitHub. Это всё, что вам нужно о нём знать. Говоря о цветах, я сделал все вышеприведенные снимки экрана в светлой теме, чтобы вас не пугать. Но если во всём остальном я предпочитаю темные цвета, то зачем терпеть мертвенно-бледный GitHub?
Здесь я использовал сочетание расширения Stylish для браузера Chrome (умеющее применять темы к любому веб-сайту) и стиля GitHub Dark. И на закуску, темная тема инструментов разработчика GitHub (встроенная, только нужно включить) и тема Atom One Dark для Chrome.
Bitbucket
Строго говоря, он здесь не совсем уместен, но я просто не могу не упомянуть Bitbucket. Два года назад я начинал проект и провел полдня за выбором оптимального git-хостинга. Так вот, Bitbucket выиграл с существенным отрывом. Их поток рецензирования кода ушел далеко вперед от конкурентов (это было задолго до того, как в GitHub появилось хотя бы понятие рецензента). С тех пор GitHub тоже обзавелся рецензиями. К сожалению, последний год мне не доводилось использовать Bitbucket – возможно, они опять ушли вперед в чём-нибудь. Так что я рекомендую тем, кто отвечает за выбор git-хостинга, обратить внимание и на Bitbucket.
Заключение
Вот и всё! Надеюсь, что сумел рассказать вам хотя бы три ранее незнакомых вам вещи. И ещё надеюсь, что вы хорошо провели время за чтением моей статьи.
Есть ли удобные wiki-сервисы с git-интерфейсом?
На Гитхаб и Гитлаб есть поддержка вики. И с этой вики даже можно работать, как с гит-репозиторием. Но работать с ними ужасно неудобно. Они медленно загружаются и медленно сохраняются. В наш век асинхронности хочется быструю вики. Пара секунд задержки при открытии-сохранении чуть-чуть бесят.
Есть пример быстрой записной книжки: Google Keep (в браузере). Редактируешь заметку, закрываешь, и она мгновенно закрылась, а сверху крутится колесико прогресса, пока все это сохраняется, но сохраняется в фоне, не мешая, не раздражая и не отнимая времени. Прелесть!
При этом, сами эти git-сервисы позволяют предоставлять доступ к репозиторию сторонним проектам.
- не быть «залоченым» на вендора (скачать себе все свои данные через git clone/pull);
- (опционально) хранить контент в Github/Gitlab;
- с удобным, красивым и асинхронным быстрым интерфейсом.
- Вопрос задан 10 нояб. 2022
- 645 просмотров
12 комментариев
Простой 12 комментариев
1 и 2 пункт это по факту одно и то же — если 1 пункт работает то автоматом работает и 2.
Александр @ForestAndGarden
Поясните, пожалуйста, почему вам нужна именно вики, если всё-равно предполагаете сохранять на Гитхабе или Гитлабе?
Ярослав @xenon Автор вопроса
Александр, не очень понимаю противоречие, на которое вы указываете (мне кажется, его нет). Мне нравится markdown для оформления текста. Нравится связность документов как в wiki. И нравится хранить данные с версиями, централизованно, локально и удаленно — поэтому GIT.
Не все же вики на mediawiki, как википедия. github/gitlab тоже имеют свои wiki движки для проектов и вопроса бы не было, если бы меня устраивали эти движки (а они не устраивают тормознутостью).
Ярослав @xenon Автор вопроса
gd1xza, выглядит прямо как то что надо, спасибо! Но привязать ни gitlab, ни github не получилось. по гитхабу вообще ветка про эту ошибку с 2018 года https://github.com/benweet/stackedit/issues/1290
Александр @ForestAndGarden
Ярослав, избыточность, а не противоречие.
Учёт изменений (версий) страниц: возможность сравнения редакций и восстановления ранних.
Возможно, вам нужен маркдун-редактор с предпросмотром страницы.
Ярослав @xenon Автор вопроса
Александр, да, согласен с вами. Markdown редактор, который будет работать с git репозиторием.
Ярослав @xenon Автор вопросаgd1xza, тем не менее, поиск по альтернативам stackedit’а довел до gitbook.com, а он уже более-менее подходил и интегрировался с gitlab’ом. Единственный минус — он не видит именно вики репозитории (вики к проектам), которые называются reponame.wiki , а видит только основные (которые reponame). но это терпимо.
Ярослав, wiki.js вроде умеет работать с git. Точно не подскажу, не тестировал, но в настройках можно настроить синхронизацию с git
Александр @ForestAndGarden
Нет гостевого доступа к странице.
Александр,
В смысле нет? Ставите Вики и раздаете права как угодноАлександр @ForestAndGarden
А теперь есть. Чудеса.
Решения вопроса 0
Ответы на вопрос 2
YakovenkoND @YakovenkoND
Попробуйте этот сервис
Ответ написан 11 нояб. 2022
Нравится 1 2 комментария
YakovenkoND @YakovenkoND
Если мой ответ вам помог, отметьте его, как решение проблемы.
Ярослав @xenon Автор вопросаСервис интересный, но мне он все таки не подошел. Нужно (в идеале) стороннее решение на чужих серверах (ну вот как github/gitlab wiki или google keep), которое бы как-то работало без своего сервера, просто из браузера с компа или телефона, а retype надо на своем сервере крутить, как dokuwiki и другие wiki движки. Еще он у меня почему-то не сохраняет изменения, но это не очень важно.
Наиболее подходящий под мои запросы (по заявленным фичам) был предложенный в комментах stackedit.io, но он фактически с github/gitlab не интегрируется (ошибки выдает). Еще нашел https://dillinger.io/ он легко с гитхабом подружился, но тоже как-то не очень.
Больше понравился вариант с obsidian+git плагин. Но он тоже, во-первых, не очень дружит с gitlab’овской разметкой и gitlab’овскую wiki приходится переправлять под него. А во-вторых, не подходит под сам вопрос (я его выбрал потому что подходящий (по заявлениям) stackedit.io на самом деле не работает).
Может быть еще появится какой-то ответ с аналогом stackedit’а, только работающим 🙂