Вы когда-нибудь бродили по github и видели классный пакет, который хотели бы использовать, только для того, чтобы увидеть, что есть readme из одной строки, не объясняющей, что он делает. Не более того, давайте документировать вещи.
Во-первых, не стоит недооценивать силу readme на github. Обычно люди начинают с этого, когда находят ваш проект. Но что там делать можно узнать в интернете. Мы проверяем следующий шаг.
И не забывайте, я не знаю всех вариантов. Я просто назову несколько, которые я знаю, люблю и использую в своих проектах.
gh-страницы (филиал)
Прямо сейчас в вашем репозитории есть ветка для начала работы на github! Если у вас есть проект, просто создайте новую ветку с именем gh-pages. Добавьте index.html и напишите код, Hello world! было бы неплохо. Загрузите это на свой github и позвольте github опубликовать все, что вам нужно.
Если ваша ветка на github называется https://github.com/disjfa/demo-pages, и вы сделали переход на gh-страницы, теперь у вас есть веб-сайт на https://disjfa.github.io/demo-pages. страниц/» (обратите внимание на / в конце). Правда там написано только Hello world! . Но мы должны с чего-то начать.
Джекилл
Теперь, когда мы знаем об этой ветке gh-pages, вам нужно кое-что знать. Github поддерживает простые html-файлы, но они также поддерживают этот генератор статических сайтов под названием jekyll. Когда вы отправляете ветку с помощью jekyll, github автоматически генерирует страницы при отправке на gh-pages .
Например, я сделал свои основные страницы github disjfa.github.io с помощью jekyll и изменил ветку gh-pages в своих настройках на мою основную ветку. Если я нажму эту ветку, я теперь получу свою страницу, как и должно быть, на https://disjfa.github.io.
Подробнее о GitHub Pages и Jekyll.
gh-страницы (узел)
Далее, мне нравится делать сайты на javascript, плагины и прочее. Или если вы просто хотите создать сайт с помощью другого генератора статических сайтов. Обычно у вас есть скрипт сборки для создания сайта. Давайте пример!
Я создал этот плагин vue, vue-route-timeline. В этом также есть несколько примеров, которые я использую для создания и проверки моего плагина. В моих сценариях npm у меня есть сценарий сборки, npm run build. Это создаст мой сайт и выведет его в папку dist. Таким образом, папка dist будет использоваться для публикации, теперь я знаю об этой ветке gh-pages! Давайте опубликуем там.
Установить gh-страницы
npm i gh-pages
И опубликовать
gh-pages -d dist
Или добавьте это в мои «скрипты» в моем package.json
"scripts": {
"gh-pages": "gh-pages -d dist",
}
Так что мы можем бежать
npm run gh-pages
Обратите внимание на -d для каталога, который мы хотим отправить. Gh-pages проверит ваш gh-pages , проверьте папку dist. И отправьте это в свою ветку gh-pages.
Таким образом, вы можете запихнуть туда все, что захотите. Я использую это в продвинутых проектах jekyll и проектах javascript. Только не забывайте, что базовая папка ваших gh-страниц не всегда является папкой /. Но папка /project-name. Мне пришлось изменить это в моих сценариях сборки по пути. Предыдущий пример моей временной шкалы можно найти здесь, https://vue-route-timeline.js.org/.
гитбук
Далее, давайте вернемся к простым временам. Github, а ридми сделан с использованием уценки. Если вы просто хотите сделать некоторую документацию, используя уценку, это было бы здорово на github, но мы можем расширить, используя gitbook.
Это центральное хранилище, где хранится документация, поэтому это простой способ создать и сохранить документ. Давайте пример!
У меня есть этот репозиторий для базового проекта Symfony, glynn-admin-symfony4. Поскольку это проект Symfony, я не могу отправить его на статическую страницу, поэтому я добавил gitbook-cli.
В моем проекте я добавил файл book.json, указывающий на папку docs.
{
"title": "Glynn admin, for symfony4",
"root": "./docs"
}
Так что это укажет на папку с моими документами. Настройте документы с помощью
gitbook init
В настройках › Интеграции и сервисы в моем репозитории я также добавил приложение gitbook, поэтому, когда я нажимаю свою ветку, gitbook знает и переиндексирует мои документы. Теперь она будет опубликована там, например, книгу, которая у меня есть, можно посмотреть здесь. И в моем репо документы также можно прочитать на github. Вы также можете проверить книгу локально, используя gitbook serve.
Готово!
Это советы и приемы, которые у меня есть для вас сегодня, мне они все нравятся. Каждый из них имеет собственный и индивидуальный способ использования. У них у всех есть что-то для проекта, который мне нравится. И с ними я создал документы, которые мне нравятся.
Секреты и уловки
CNAME. Если у вас есть собственный домен, вы можете указать его на домен github.io и использовать его в качестве домена для своих примеров. Сайт размещен на github, и у вас есть доменное имя. В качестве примера на предыдущей ссылке для моей временной шкалы vue route я установил cname здесь. Указание на https://vue-route-timeline.js.org. Теперь, если вы перейдете на домен github.io, вы будете перенаправлены на ранее упомянутый URL-адрес. Как видите здесь https://disjfa.github.io/vue-route-timeline.
И dns.js.org, как упоминалось ранее. DNS для javascript-проектов. Если вы подтолкнете изменение для своего домена *.js.org, они будут потрясающими и позволят вам получить URL-адрес своего домена. Они ссылаются только на статические сайты на github, поэтому их можно использовать в качестве примеров, как я показал!
Наслаждаться!
Теперь я надеюсь, что вы создадите примеры, документы, советы и рекомендации для всех проектов, которые вы создаете. Давайте строить потрясающие вещи! Хлопайте, если вам это нравится, и если вы хотите рассказать мне, что вы сделали, вы всегда можете сообщить мне об этом в твиттере!
Фото автора Yingpis Kalayom на Unsplash
