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

Ответ 1

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

• git checkout gh-pages
• mkdir _layouts
• mv index.html _layouts
• git checkout master -- README.md
• mv README.md index.md
• Подготовьте следующий текст к index.md

---
layout: index
---

Вам также нужно открыть файл index.html и внести следующие изменения:

• Удалите отображаемый HTML из уценки в вашем файле README.md. Обычно это происходит между тегами <section> или <article>. Замените этот HTML-текст текстом {{ content }}, это позволит нам использовать этот файл как jekyll. Файл, к которому мы применяем макет, будет размещен там, где находится тег содержимого.

• Найдите CSS для темы страницы проекта. для меня это была строка вроде следующего:

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

  Это нужно изменить на

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

• Любые другие активы, хранящиеся на вашем сайте, которые будут использоваться в этом макете, также должны иметь префикс {{ 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: Я обновил выше script для файла README.md и уценки в docs/*, чтобы использовать тот же файл макета. Это намного лучше, чем раньше. Этот script находится в вашем каталоге .git/hooks/. bash должен находиться на вашем пути.

Создайте файл _config.yml со следующим

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

Вышеупомянутый script также синхронизирует файлы разметки, найденные в каталоге docs/* ветки master, чтобы их можно было просматривать на сайте GitHub Pages. Относительная привязка к этим документам работает, если вы включили следующую функцию jQuery, чтобы разделить расширение .md от якорей на ветке gh-pages. Вы можете добавить следующие script в 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 не будет обрабатываться правильно. Чтобы исправить это, я обновил это до следующего script, который более тщательно проверяет href и удаляет расширение, если оно найдено. Я также сделал script более общим, позволяя использовать его для удаления других расширений путем изменения переменной 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));
    });
});

Я устанавливаю пример repo в CoryG89/docsync, который имеет страница проекта здесь, если вы хотите увидеть, как все это работает вместе.

Ответ 2

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

• Извлеките README.md из https://api.github.com/repos/<owner>/<repo>/contents/README.md.
• Декодировать ответ Base64: window.atob( JSON.parse( blob ).content );

• Поместить декодированный README в https://api.github.com/markdown в тело JSON

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

• Вставьте отображаемый HTML в элемент DOM, как это сделано Brad Rhodes.

Два оговорки к этому подходу:

• Выполнение двух последовательных запросов замедляет загрузку страницы.
• Может появиться ограничение скорости при доступе к API Github.

Для страницы с низким трафиком, где время загрузки не является критическим (~ 1-2 сек.), этот метод работает достаточно хорошо.

Ответ 3

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

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

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

Ответ 4

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

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

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

Ответ 5

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

• Используйте API Github и JSONP для извлечения документа из Github
• Декодировать содержимое base64 в ответе от API Github
• Отметьте уценку с помощью механизма разметки javascript.
• Отобразить отображаемый html

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

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

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

Ответ 6

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

Ответ 7

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

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

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

Инструкция

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

• Замена "USER" вашим именем пользователя GitHub
• Замена "REPO" на ваше репо-имя GitHub
• Замена "вашего проекта" на ваше имя проекта

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

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

Ответ 8

Я также хочу редактировать документы в master и публиковать в gh-страницах - мне нравится держать документы в курсе исходного кода, и это кажется лучшим способом. Для меня это незавершенное дело, но я принял Cory script в качестве отправной точки и немного расширил его, чтобы он работал из коробки, пока является ветвью gh-страниц с _layouts (т.е. сайтом jekyll). Он преобразует фехтование стиля обратного хода (для блоков кода), которые отлично работают в режиме просмотра github, но не на gh-страницах. Я использую index.md с include для проекта 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 его построит на сервере.

Ответ 9

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

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

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

Ответ 10

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

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

Стоит проверить как настроить суперболотный сайт 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

Automating

Тогда нам просто нужно автоматизировать задачу копирования всех изменений из master в ветвь gh-pages перед каждым нажатием. Мы можем сделать это, запустив этот script (вы можете скопировать и вставить его в терминал)

$(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.

Что это. Готово.