Як я можу синхронізувати документацію зі сторінками Github?

81

У мене є проект разом із кількома людьми, і у нас є README.mdфайл із купою GitHub Flavored Markdown, який відображається на нашій сторінці GitHub. Ми також створили гілку Сторінок GitHub, яка розміщується в піддомені нашої організації GitHub, і використовували автоматичний генератор сторінок, який просто завантажувався у наш README.mdфайл, коли ми створювали нашу сторінку. Однак я помічаю, що коли я оновлюю наш README.mdфайл, він не оновлює сторінку проекту. Натомість нам потрібно перейти на вкладку налаштувань GitHub і відтворити сторінку проекту, перезавантаживши README.mdфайл, коли ми це зробимо.

Крім того, прочитавши про відносне зв’язування роботи між файлами документації на сторінках каталогів проекту GitHub. Мені дуже подобається націнка, оскільки це економить багато часу від необхідності писати весь HTML вручну для нашої документації. Однак я хотів би мати один README.mdфайл, який міг би включати відносні посилання на інші файли документації, розташовані за адресою docs/*.md. Я сподівався, що є просте рішення, так що інші мої файли документації також можуть бути включені до моєї гілки gh-сторінок та розміщені під моїм субдоменом GitHub Pages і будуть відтворені та / або тематизовані.

Іншими словами, мої запитання такі:

  • Чи є спосіб, щоб мій файл README.md автоматично оновлювався на моєму субдомені Сторінка Github?
    • [РЕДАКТУВАТИ]: Ні, здається, не є відповіддю при використанні автоматичного генератора сторінок. Ви повинні перейти на сторінку налаштувань репозиторію та перезавантажувати його щоразу, коли змінюються, щоб оновити його.
       
  • Чи є спосіб, як відносні посилання на мою документацію у моєму файлі README.md працюють на моїх Сторінках Github, можливо, я якось синхронізую свої /docs/*.mdз моїми сторінками Github і якимось чином відображаю та / або тематизую їх?
    • [EDIT]: З того, що я дізнався , так як пишу це питання, здається , що це можливо тільки на сторінках GitHub через використання генератора статичного сайту , як рубін коштовний камінь Джекіл і , ймовірно , деякі використань webhooks підтримуваних GitHub , які згадані у коментарях нижче. Зараз я намагаюся знайти оптимальне рішення.
       
  • А ще краще, чи є ще простіший спосіб я це зробити і, можливо, маю лише одну копію мого README.md та документацію, яка використовується як на gh-сторінках, так і в моїй основній гілці, і робить все найпростішим?
    • [РЕДАКТУВАТИ]: Здається, це майже напевно ні. Я думав про можливість чогось вбудованого в GitHub, щоб це дозволило. Здається, що в майбутньому на Сторінках GitHub може бути вбудована краща підтримка такого роду речей, або, принаймні, я точно сподіваюсь, що це буде.
       
git  github  github-pages  webhooks 
— Корі Гросс
джерело
3
GitHub має підтримку веб-хуків після отримання. Ви замислювались над тим, щоб додати хук, який викликає якийсь віддалений сценарій, який штовхає нову README.mdверсію на сторінки GitHub?
— ubik
7
Дякуємо, що ви чудові та редагуєте свої висновки. На цьому сайті не так багато людей.
— Метт Кантор,
Для першого питання, ось ручний підхід , а не автоматичний, але він простий і працює. Для частини генерації HTML можна використовувати dillinger.io . Я також знайшов цей автоматичний метод , хоча я спробував, але не змусив його працювати.
— ілед
1
GitHub щойно дозволив використовувати будь-яку гілку та каталог як джерело для документів . Вам більше не доведеться користуватися gh-pages.
— Дан Даскалеску,

Відповіді:

37

Я збираюся опублікувати рішення, яке я встановив, яке використовує той факт, що GitHub Pages використовує Jekyll, який вже використовує автоматичний генератор сторінок.

  1. git checkout gh-pages
  2. mkdir _layouts
  3. mv index.html _layouts
  4. git checkout master -- README.md
  5. mv README.md index.md
  6. Додайте наступний текст до index.md

 

---
layout: index
---

Вам також потрібно відкрити index.htmlфайл і внести такі зміни:

  1. Видаліть відтворений HTML із розмітки у вашому README.mdфайлі. Зазвичай це між тегами <section>або <article>. Замініть цей HTML текстом {{ content }}, що дозволить нам використовувати цей файл як джекілл. Файл, до якого ми застосовуємо макет, буде розміщений там, де знаходиться тег вмісту.

  2. Знайдіть CSS для теми сторінки проекту. для мене це був такий рядок:

    <link rel='stylesheet' href='stylesheets/stylesheet.css' />

    Це потрібно змінити на

    <link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />

  3. Будь-які інші ресурси, що зберігаються на вашому веб-сайті, які будуть використовуватися в цьому макеті, також повинні мати префікс {{ site.path }}.

Роблячи це, Jekyll відобразить файл index.htmlрозмітки як вміст макета в _layoutsкаталозі. Для автоматизації цього процесу не лише для файлу README.md, але й для інших документів, які можуть бути у вашій головній гілці, я зробив наступні кроки:

Створив файл із назвою, post-commitщо містить таке:

 

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # Layout prefix is prepended to each markdown file synced
    ###################################################################
    LAYOUT_PREFIX='---\r\nlayout: index\r\n---\r\n\r\n'

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    echo -e $LAYOUT_PREFIX > index.md
    cat README.md >> index.md
    rm README.md
    git add index.md
    git commit -a -m "Sync README.md in master branch to index.md in gh-pages"

    # Sync the markdown files in the docs/* directory
    ###################################################################
    git checkout master -- docs
    FILES=docs/*
    for file in $FILES
    do
        echo -e $LAYOUT_PREFIX | cat - "$file" > temp && mv temp "$file"
    done

    git add docs
    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

EDIT: Я оновив вищезазначений сценарій як для README.mdфайлу, так і docs/*для розмітки, щоб обидва використовували один і той же файл макета. Це набагато краща настройка, ніж у мене раніше. Цей скрипт знаходиться у вашому .git/hooks/каталозі. bash повинен бути на вашому шляху.

Створіть файл _config.ymlнаступним чином

markdown: redcarpet
path: http://username.github.io/reponame

Наведений вище сценарій також синхронізує файли розмітки, знайдені в docs/*каталозі masterгілки, для того, щоб їх можна було також переглядати на сайті GitHub Pages. Відносне посилання на ці документи працює, якщо ви включите наступну функцію jQuery для того, щоб позбавити .mdрозширення від прив'язок на gh-pagesгілці. Ви можете додати наступний скрипт index.htmlв _layoutsкаталозі:

$(document).on('ready', function () {
    $('a').each(function (i, e) {
        var href = e.href;
        if (href.search('.md') > 0)
            $(this).attr('href', href.split('.md')[0]);
    });
});

EDIT: Я змінив наведений вище код у своєму сховищі, це був швидкий і брудний спосіб зробити це, але він не буде працювати належним чином у всіх випадках, якщо ви розумієте, що я маю на увазі .. Наприклад, файл розмітки company.mdata.mdне буде оброблений правильно. Щоб виправити це, я оновив це до наступного сценарію, який більш ретельно перевіряє href та видаляє розширення, якщо його знайдено. Я також зробив сценарій більш загальним, дозволивши використовувати його для видалення інших розширень, змінивши extзмінну. Ось код:

$(function () {
    $('a').each(function () {
        var ext = '.md';
        var href = $(this).attr('href');
        var position = href.length - ext.length;
        if (href.substring(position) === ext)
            $(this).attr('href', href.substring(0, position));
    });
});

Я встановлюю приклад репозиторію на CoryG89 / docsync , який має тут сторінку проекту , якщо ви хочете побачити, як все це працює разом.

— Корі Гросс
джерело
4
Я нагороджую вас своєю нагородою за таку ґрунтовну відповідь, але я все ще сподіваюся, що хтось придумає більш прямолінійне рішення.
— Метт Кантор
1
Я ціную, що Метт. Я збираюся продовжити і використати 50 представників, щоб надати ще одну нагороду в надії на інше простіше / простіше рішення для цього. Це рішення приємне, оскільки воно дозволяє відносним посиланням продовжувати працювати, як очікувалося, між вашим README та іншими документами щодо розмітки на вашому сайті, а також у вашому репо.
— Корі Гросс
1
Чи не було б простіше просто зняти розширення .md у гачку після фіксації? А може, навіть є спосіб зробити це, використовуючи самого Дженкінса?
— jjmerelo
Я думаю, що ви повинні зберігати файли у сховищі з розширенням .md, інакше це не відображатиметься як Markdown. Хоча це не на 100%.
— Кори Гросс
2
є щось більш просте у 2016 році?
— Пітер Краус
5

Моє рішення проблеми синхронізації README зі сторінкою Github дещо відхиляється від вищезазначеного. Замість використання окремого механізму JavaScript Markdown можна використовувати API Github для повернення файлу Markdown, який відображається як HTML.

  1. Отримайте README.mdвід https://api.github.com/repos/<owner>/<repo>/contents/README.md.
  2. Розшифруйте відповідь Base64: window.atob( JSON.parse( blob ).content );

  3. Розмістіть декодований READMEдо https://api.github.com/markdownв тілі JSON

     {
   "text": "<README>",
   "mode": "markdown",
   "context": "<owner>/<repo>"
 }

  4. Вставте відтворений HTML в елемент DOM, як це зробив Бред Родс .

Два застереження до цього підходу:

  1. Виконання двох послідовних запитів уповільнює завантаження сторінки.
  2. Може мати обмеження швидкості під час доступу до API Github.

Для сторінки з низьким трафіком, де час завантаження не є критичним (~ 1-2 сек), тоді вищевказаний метод працює досить добре.

— кгрит
джерело
atob () чудово працює в Chrome і FF, але не в IE 11. Каже недійсний символ. сайт знаходиться нижче joymon.github.io/joyful-visualstudio
— Joy George Kunjikkuru
3

У мене є кілька ідей щодо спільного використання одного файлу readme між вашим сайтом документації та основним репозиторієм github:

  1. Ви можете використовувати лише одну гілку gh-сторінок, яка містить і ваш код, і сайт документації про jekyll. Ваше сховище може стати трохи захаращеним, і вам потрібно буде розмістити заголовок YAML у верхній частині readme. Він майже підтримує відносне посилання. Проблема в тому, що якщо ви хочете, щоб jekyll зробив вашу націнку, він отримає розширення .html. Можливо, є спосіб це налаштувати. Ось приклад, який я зібрав разом, щоб перевірити, чи працює це.

  2. Ви можете використовувати виклики AJAX на вашому сайті документації, щоб прочитати readme з вашої основної гілки, а потім відтворити його за допомогою візуалізатора Javascript Markdown . Це завантажиться трохи довше, і воно не буде підтримувати відносні посилання, якщо ви не напишете розумний Javascript. Це також більше роботи для реалізації, ніж ідея 1.

— Натан Брейт
джерело
3

Ще одним маршрутом, який слід розглянути, є встановлення гачка перед фіксацією, який створює відповідні сторінки. Я роблю це в одному зі своїх сховищ . Вам, мабуть, доведеться відмовитися від автоматичного генератора сторінок і просто натиснути на gh-pagesгілку самостійно, а також зробити щось фантазійне, щоб перетворити ваші документи в HTML або на сайт Jekyll, як пропонує Натан .

У цьому сховищі я натискаю так, щоб зберегти gh-pagesідентичність master. Існує також безліч інших способів це зробити. Це, можливо, не ідеально підходить для вашої ситуації (можливо, ви не хочете, щоб вони були ідентичними).

У будь-якому випадку, причина, по якій я запропонував нагороду з цього питання, полягала в тому, що я сподівався, що хтось має кращий робочий процес. Цей метод виглядає заплутаним і негнучким, і він вимагає, щоб усі синхронізували свої гачки.

— Метт Кантор
джерело
2

Ще один метод, з яким я почав працювати досить успішно, - використання Ajax для отримання документів за допомогою API Github та механізму розмітки Javascript для відображення HTML (як це також запропонував Натан).

  1. Використовуйте API Github та JSONP, щоб отримати документ із Github
  2. Розшифруйте вміст base64 у відповіді від Github API
  3. Рендеруйте націнку за допомогою механізму розмітки JavaScript
  4. Відображення відображеного html

Натан висловив певне занепокоєння з приводу продуктивності, але, на моєму досвіді, це, здається, миттєво завантажується, тому я не думаю, що насправді це проблема.

Перевага полягає в тому, що його легко налаштувати, і він завжди буде оновлювати ваші документи, навіть якщо ви просто редагуєте націнку безпосередньо у браузері на github.

Я створив приклад на сторінках Github за адресою http://bradrhodes.github.io/GithubDocSync/, щоб показати, як він працює.

— Бред Родс
джерело
Я поєднав метод з клонуванням, щоб показати свій project.wiki на сторінках GitHub .
— Четабахана,
2

Ще однією можливістю методу, описаного Натаном та Брендом Родосом, є використання чудового інструменту: FlatDoc, створеного Ріко Ста. Круз.

FlatDoc завантажить за допомогою ajax документацію (README.md або будь-який інший файл розмітки), проаналізує її та відобразить з усіма смайлами та навіть меню бічної панелі для навігації!

Він вбудував у свій api допоміжний метод для завантаження файлів з майстра репозитарію GitHub (але також може завантажувати будь-де в Інтернеті).

Інструкції

Почніть з копіювання наступного HTML-шаблону у ваш index.html у вашій гілці gh-сторінок. Продовжуйте з:

  • Заміна "USER" на ваше ім’я користувача GitHub
  • Заміна "REPO" на ваше ім'я репозиторію GitHub
  • Заміна "Ваш проект" на назву вашого проекту

у файлі. Спробуйте локально у своєму браузері. Потім зафіксуйте і натисніть зміни. Тепер ваша сторінка github завжди буде оновлюватися вашим файлом README.md у вашій головній гілці.

Якщо тема за замовчуванням не задовольняє вас, ви можете переформатувати її за допомогою власного css.

— Халід Саломао
джерело
1

Я також хочу редагувати документи в master і публікувати на gh-сторінках - я люблю постійно оновлювати документи з вихідним кодом, і це здається найкращим способом. Для мене це незавершена робота, але я взяв сценарій Кори як вихідну точку і трохи розширив його, щоб він працював нестандартно, доки існує гілка gh-сторінок _layouts(тобто сайт jekyll). Він перетворює огородження в стилі backtick (для блоків коду), які чудово працюють під час перегляду джерел github, але не на gh-сторінках. Я використовую для index.mdвключення для проекту, README.mdщоб я міг додати заголовок та деякі інші прикраси. Ця версія також обробляє документацію в будь-яких вкладених каталогах під назвою "docs", що я вважаю корисним у проекті з декількома модулями (не підмодулі git, а лише підкаталоги):

.git/hooks/post-commit

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # function to convert a plain .md file to one that renders nicely in gh-pages
    function convert {
        # sed - convert links with *.md to *.html (assumed relative links in local pages)
        # awk - convert backtick fencing to highlights (script from bottom of file)
        sed -e 's/(\(.*\)\.md)/(\1.html)/g' "$1" | awk -f <(sed -e '0,/^#!.*awk/d' $0) > _temp && mv _temp "$1"
    } 

    if ! git show-ref --verify --quiet refs/heads/gh-pages; then
        echo "No gh-pages, so not syncing"
        exit 0
    fi

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    mkdir -p _includes

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    if [ -f README.md ]; then
        cp README.md _includes/
        convert _includes/README.md
        git add README.md
        git add _includes/README.md
    fi

    # Generate index if there isn't one already
    ###################################################################
    if [ ! -f index.md ]; then
        echo -e '---\ntitle: Docs\nlayout: default\n---\n\n{% include README.md %}' > index.md
        git add index.md
    fi

    # Generate a header if there isn't one already
    ###################################################################
    if [ ! -f _includes/header.txt ]; then
        echo -e '---\ntitle: Docs\nlayout: default\nhome: \n---\n\n' > _includes/header.txt
        git add _includes/header.txt
    fi

    # Sync the markdown files in all docs/* directories
    ###################################################################
    for file in `git ls-tree -r --name-only master | grep 'docs/.*\.md'`
    do
        git checkout master -- "$file"
        dir=`echo ${file%/*} | sed -e "s,[^/]*,..,g"`
        cat _includes/header.txt | sed -e "s,^home: .*$,home: ${dir}/," > _temp
        cat "$file" >> _temp && mv _temp "$file"
        convert "$file"
        git add "$file"
    done

    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

exit $?

#!/usr/bin/awk
{
   # Replace backtick fencing (renders well when browsing github) with jekyll directives
   if (/```/) {
      IN = IN?0:1 # Are we already in a fenced section? Toggle.
      if (IN) { # If we are starting a fenced section
         if (/```\s*$/) {
           $0 = $0"text" # empty language is OK for backticks but not for jekyll
         }
         gsub(/```/, "{% highlight ")
         print $0" %}"
      } else { # ending a fenced section
        print "{% endhighlight %}" 
      }
    } else { # not a fencing line
      if (IN) { # but in a fenced section, so add indent to make sure code is rendered with <pre>
        print "    "$0
      } else {
        print
      }
    }
}

Іншим відхиленням від оригіналу є те, що він встановлює змінну page.homeна всіх сторінках. Це може бути використано для визначення відносного шляху кореневого каталогу, тому його можна використовувати для пошуку статичних ресурсів, таких як css. У _layouts/.default.htmlмене є:

<link rel="stylesheet" href="{{ page.home }}css/main.css">

Таким чином я можу редагувати css, побудувати сайт jekyll локально та переглянути результат у браузері, не чекаючи, поки github побудує його на сервері.

— Дейв Саєр
джерело
0

Нещодавно я зробив пакет gh-pages-generator для вирішення цієї проблеми - він генерує багатосторінковий сайт, використовуючи декілька файлів MD та файл конфігурації.

Він коректно оновлює всі посилання між сторінками. Відносно легко зробити його частиною CI, щоб здійснити зміни назад до гілки gh-сторінок.

Я використовую його тут і тут .

— особливо
джерело
0

Це не складно , дві копії та вставки в термінал, і все готово.

Jekyllдозволяє імпортувати файл розмітки, а потім він подбає про перетворення їх у HTML. Хитрість полягає в тому, щоб імпортувати README.mdв ваш index.mdфайл з {% include_relative README.md %}. Ось як ми можемо це зробити:

Варто перевірити, як налаштувати сайт super barebones Jekyllна github (це всього два файли! )

Налаштування

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

# Copy our two files to the gh-pages branch
git checkout -b gh-pages &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/_config.yml &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/index.md &&
#
# Commit and publish our page on github
git add -A && git commit -m "Create project github page" &&
git push --set-upstream origin gh-pages |
#
git checkout master # go back to master branch

Автоматизація

Тоді нам просто необхідно автоматизувати завдання копіювання всіх змін masterв gh-pagesгалузь перед кожним натисканням. Ми можемо зробити це, запустивши цей скрипт ( ви можете скопіювати та вставити його в термінал )

$(cat > .git/hooks/pre-push << EOF
#!/bin/sh
we_are_in_gh_pages="\$(git branch | grep -G "* gh-pages")"

if [ ! "\$we_are_in_gh_pages" ];
  then
    git checkout gh-pages &&
    git rebase master &&
    git push -f &&
    git checkout master # go back to master branch
fi
EOF
) && chmod 775 .git/hooks/pre-push

Це створить поштовх-гачок, який буде копіювати всі зміни з masterгілки при gh-pagesкожному запуску git push.

Це воно. Готово.

— Марсело Лазароні
джерело
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.