Как синхронизировать документацию со страницами Github?

мое решение проблемы синхронизации README со страницей Github немного отличается от приведенного выше. Вместо того чтобы использовать отдельный движок, уценки на JavaScript, можно использовать 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-2sec), то приведенный выше метод работает достаточно хорошо.

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

1. вы можете использовать только одну ветвь gh-pages, которая содержит как ваш код, так и сайт документации jekyll. Ваш репозиторий может быть немного загроможден, и вам нужно будет поместить заголовок YAML в верхней части readme. Это почти поддерживает относительные ссылки. Проблема в том, что если вы хотите, чтобы Джекилл отображал вашу уценку, он даст ее один.расширение html. Может быть, есть способ настроить это. вот пример, который я собрал вместе, чтобы посмотреть, работает ли он.

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

другой маршрут для рассмотрения-это настройка pre-commit hook, которая основывается на соответствующих страницах. Я делаю это в один из моих репозиториев. Вам, вероятно, придется отказаться от автоматического генератора страниц и просто нажать на gh-pages ветви себя, хотя, а также делать что-то необычное, чтобы превратить ваши документы в HTML или сайт Jekyll как Натан предлагает.

В этом репозитории я толкаю вот так сохранить gh-pages идентичны master. Есть много другие способы чтобы сделать это, тоже. Это может быть не идеально для вашей ситуации, хотя (вы не можете хотеть, чтобы они были идентичны).

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

можно использовать DocumentUp для визуализации вашего README.md.

еще один метод, который я получил для работы довольно успешно использует Ajax для извлечения документов с помощью API Github и JavaScript markdown engine для визуализации HTML (Как также предложил Натан).

1. используйте API Github и JSONP, чтобы получить документ из Github
2. Декодируйте содержимое base64 в ответе от API Github
3. визуализация уценки с помощью javascript markdown engine
4. отобразить HTML-код

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

преимущество в том, что его легко настроить, и он всегда будет обновлять ваши документы, даже если вы просто редактируете уценку непосредственно в браузере на github.

Я установил пример на страницах Github в http://bradrhodes.github.io/GithubDocSync/ чтобы показать, что это работает.

еще одна возможность для метода, описанного Натаном и брендом Родосом, - использовать отличный инструмент:FlatDoc создано Rico Sta. Круз.

FlatDoc загрузит ajax документацию (README.md или любой другой файл markdown), проанализируйте его и отобразите со всеми лакомствами и даже боковым меню для навигации!

Он имеет встроенный в свой api вспомогательный метод для загрузки файлов из GitHub repo master (но также может загружать в любом другом месте из сеть.)

- инструкции

начните с копирования следующего html шаблон в свой индекс.html в вашей ветке gh-pages. Продолжайте:

• замена "пользователя" на ваше имя пользователя GitHub
• замена "РЕПО" на ваше имя РЕПО GitHub
• замена "ваш проект" с вашим именем проекта

в файле. Попробуйте локально в браузере. Затем commit и push в изменения. Теперь ваша страница github всегда будет обновляться с помощью вашего README.md файл в главной ветке.

Если тема по умолчанию не удовлетворяет Вас, Вы можете изменить ее стиль с помощью собственного css.

Я также хочу редактировать документы в master и публиковать на gh-страницах - мне нравится обновлять документы с исходным кодом, и это кажется лучшим способом. Это работа для меня, но я взял сценарий Кори в качестве отправной точки и немного расширил его, чтобы он работал из коробки, пока есть ветвь gh-pages с _layouts (т. е. сайт Джекил). Он преобразует фехтование в стиле backtick (для блоков кода), которые хорошо работают в просмотре исходного кода github, но не в ГХ-страницы. Я использую 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)/(.html)/g' "" | awk -f <(sed -e '0,/^#!.*awk/d' ) > _temp && mv _temp ""
    } 

    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*$/) {
            = "text" # empty language is OK for backticks but not for jekyll
         }
         gsub(/```/, "{% highlight ")
         print " %}"
      } 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 "    "
      } else {
        print
      }
    }
}

другой вариант от оригинала заключается в том, что он устанавливает переменную page.home на всех страницах. Это может быть использовано для определения относительного пути корня diractory, поэтому его можно использовать для поиска статических ресурсов, таких как css. В _layouts/.default.html Я:

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

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

Я недавно сделал пакет gh-pages-generator чтобы решить эту проблему-он генерирует многостраничный сайт, используя несколько файлов MD и файл конфигурации.

Он корректно обновляет все ссылки между страницами. Относительно легко сделать его частью CI для фиксации изменений обратно в ветку gh-pages.

Я использую его здесь и здесь.

это не сложно, две копии и вставки в терминал, и вы все настроены.

Jekyll позволяет импортировать файл markdown, а затем он позаботится о преобразовании их в HTML. Фокус в том, чтобы импортировать ваш README.md в своем С {% include_relative README.md %}. Вот как мы можем это сделать:

это стоит проверить как настроить супер barebones Jekyll сайт на github (это просто два файлы!)

настройки

вы можете скопировать два файла и иметь свою страницу с вашим текущим readme, просто запустив это один раз настройка (скопируйте весь блок кода и pase в терминал):

# 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.

вот и все. Сделанный.