web-dev-qa-db-fra.com

Comment synchroniser la documentation avec Github Pages?

J'ai un projet avec plusieurs personnes et nous avons un fichier README.md avec un tas de GitHub Flavored Markdown qui est rendu sur notre page GitHub. Nous avons également créé une branche GitHub Pages hébergée dans le sous-domaine de notre organisation GitHub et utilisé le générateur de pages Automatic en chargeant simplement dans notre fichier README.md lors de la création de notre page. Cependant, je remarque que lorsque je mets à jour notre fichier README.md, il ne met pas à jour la page de projet. Au lieu de cela, nous devons accéder à l’onglet Paramètres GitHub et recréer la page du projet, en rechargeant le fichier README.md lorsque nous le faisons. 

De même, après la lecture de lien relatif , travailler entre les fichiers de documentation sur les pages du répertoire du projet GitHub. J'aime beaucoup le démarquage car il permet de gagner beaucoup de temps, car il faut écrire tout le code HTML manuellement pour notre documentation. Ce que j'aimerais cependant, c'est pouvoir avoir un fichier README.md qui puisse inclure des liens relatifs vers d'autres fichiers de documentation situés à docs/*.md. J'espérais qu'il existait une solution simple pour que mes autres fichiers de documentation puissent également être inclus dans ma branche gh-pages et être hébergés sous mon sous-domaine GitHub Pages et être restitués et/ou thématisés.

En d'autres termes, mes questions sont:

  • Existe-t-il un moyen de mettre mon fichier README.md à jour automatiquement sur mon sous-domaine Github Page?
    • [EDIT]: No semble être la réponse si vous utilisez le générateur de page automatique. Vous devez vous rendre sur la page des paramètres du référentiel et le recharger à chaque changement afin de le mettre à jour.
  • Existe-t-il un moyen de faire en sorte que mes liens relatifs vers ma documentation sur mon fichier README.md fonctionnent sur mes pages Github, peut-être en quelque sorte synchronisant mon /docs/*.md sur mes pages Github et en quelque sorte les rendant et les thématisant?
    • [EDIT]: D'après ce que j'ai appris depuis la rédaction de cette question, il apparaît que ceci n'est possible que sur les pages GitHub en utilisant un générateur de site static comme le joyau Ruby Jekyll et probablement quelques utilisations des webhooks supportés par GitHub qui sont mentionnés dans les commentaires ci-dessous. J'essaie actuellement de trouver une solution optimale.
  • Mieux encore, y a-t-il un moyen encore plus simple de le faire et peut-être de ne disposer que d'une copie de mon fichier README.md et de la documentation utilisée à la fois sur gh-pages et dans ma branche principale, ce qui simplifie au maximum les choses?
    • [EDIT]: Il semble que celui-ci soit presque définitivement un non. Je pensais à la possibilité que quelque chose construit dans GitHub permette cela. Il semble qu'un meilleur support pour ce genre de choses pourrait être intégré dans GitHub Pages à l'avenir, ou du moins j'espère vraiment que ce sera le cas.
gitgithubgithub-pageswebhooks
79
Cory Gross

Je vais publier une solution que j'ai configurée et qui tire parti du fait que GitHub Pages utilise Jekyll en utilisant déjà le générateur de page automatique.

  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. Ajoutez le texte suivant au index.md 

---
layout: index
---

Vous devez également ouvrir le fichier index.html et apporter les modifications suivantes:

  1. Supprimez le code HTML rendu du démarquage dans votre fichier README.md. Cela se situe généralement entre les balises <section> et <article>. Remplacez ce code HTML par le texte {{ content }}, ce qui nous permettra d’utiliser ce fichier en tant que jekyll. Le fichier auquel nous appliquons la mise en page sera placé à l'emplacement de la balise de contenu.

  2. Localisez le CSS pour le thème de votre page de projet. pour moi, c'était une ligne comme celle-ci:

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

    Cela doit être changé pour

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

  3. Tous les autres éléments stockés sur votre site qui seront utilisés dans cette présentation devront également porter le préfixe {{ site.path }}.

Ce faisant, Jekyll convertira le fichier de démarquage en contenu de la disposition index.html dans le répertoire _layouts. Afin d'automatiser ce processus non seulement pour le fichier README.md, mais également pour les autres documents que vous pouvez avoir dans votre branche principale, j'ai suivi les étapes suivantes:

Créé le fichier appelé post-commit contenant les éléments suivants:

#!/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: J'ai mis à jour le script ci-dessus pour le fichier README.md et le démarquage dans docs/* afin qu'ils utilisent le même fichier de présentation. C'est une bien meilleure configuration que celle que j'avais auparavant. Ce script va dans votre répertoire .git/hooks/. bash doit être sur votre chemin.

Créez le fichier _config.yml avec les éléments suivants

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

Le script ci-dessus synchronise également les fichiers de démarquage trouvés dans le répertoire docs/* de la branche master, afin de pouvoir également les visualiser sur le site GitHub Pages. La liaison relative à ces documents fonctionne si vous incluez la fonction jQuery suivante afin de supprimer l’extension .md des ancres de la branche gh-pages. Vous pouvez ajouter le script suivant à index.html dans le répertoire _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: J'ai changé le code ci-dessus dans mon référentiel, c'était une façon rapide et sale de le faire, mais cela ne fonctionnera pas correctement dans tous les cas si vous voyez ce que je veux dire. company.mdata.md ne serait pas traité correctement. Pour résoudre ce problème, j'ai mis à jour le script suivant qui vérifie plus attentivement le href et supprime l'extension si elle est trouvée. J'ai également rendu le script plus générique, lui permettant ainsi de supprimer d'autres extensions en modifiant la variable ext. Voici le code:

$(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));
    });
});

J'ai installé un exemple de dépôt dans CoryG89/docsync , qui a une page project ici , si vous voulez voir comment tout cela fonctionne ensemble.

36
Cory Gross

Ma solution au problème de la synchronisation d'un README avec une page Github s'écarte légèrement de la précédente. Au lieu d'utiliser un moteur JavaScript Markdown distinct, vous pouvez utiliser l'API Github pour renvoyer un fichier Markdown au format HTML. 

  1. Récupérez le README.md à partir de https://api.github.com/repos/<owner>/<repo>/contents/README.md.
  2. Décoder la réponse Base64: window.atob( JSON.parse( blob ).content );

  3. Postez la README décodée sur https://api.github.com/markdown dans un corps JSON

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

  4. Insérez le code HTML rendu dans un élément DOM, comme indiqué par Brad Rhodes .

Deux mises en garde à cette approche:

  1. L'exécution de deux demandes en série ralentit le chargement de la page.
  2. Peut rencontrer des limites de taux lors de l'accès à l'API Github.

Pour une page à faible trafic où le temps de chargement n'est pas critique (~ 1-2sec), alors la méthode ci-dessus fonctionne assez bien.

5
kgryte

Vous pouvez utiliser DocumentUp pour afficher votre fichier README.md.

4
niutech

J'ai quelques idées pour partager un seul fichier lisez-moi entre votre site de documentation et le dépôt principal de github:

  1. Vous ne pouvez utiliser qu'une seule branche gh-pages contenant à la fois votre code et un site de documentation jekyll. Votre référentiel peut devenir un peu encombré et vous devrez mettre un en-tête YAML en haut du fichier Lisez-moi. Il presque supporte les liens relatifs. Le problème est que si vous voulez que jekyll rende votre démarque, cela lui donnera une extension .html. Peut-être qu'il y a un moyen de configurer cela cependant. _ { Voici un exemple que j'ai assemblé pour voir si cela fonctionne. } _

  2. Vous pouvez utiliser les appels AJAX de votre site de documentation pour lire le fichier readme de votre branche principale, puis le restituer avec un rendu Javascript Markdown Cela prendra un peu plus de temps à charger et ne supportera pas les liens relatifs sans que vous n'écriviez du code Javascript intelligent. C'est aussi plus de travail à mettre en œuvre que l'idée 1.

3
Nathan Breit

Un autre chemin à considérer est la mise en place d'un crochet pre-commit qui construit les pages pertinentes. Je le fais dans un de mes dépôts . Vous devrez probablement abandonner le générateur de page automatique et appuyer simplement sur la branche gh-pages vous-même, tout en faisant quelque chose d'extraordinaire pour transformer vos documents en HTML ou en un site Jekyll, comme le suggère Nathan suggère .

Dans ce repository I Push like this pour garder gh-pages identique à master. Il y a beaucoup de d'autres façons de le faire aussi. Cela pourrait ne pas être idéal pour votre situation cependant (vous pourriez ne pas vouloir qu’elles soient identiques).

Quoi qu'il en soit, la raison pour laquelle j'avais offert une prime sur cette question était parce que j'espérais que quelqu'un aurait un meilleur flux de travail. Cette méthode est un peu compliquée et inflexible et elle oblige tout le monde à garder ses crochets synchronisés.

3
Matt Kantor

Une autre possibilité pour la méthode décrite par Nathan et Brand Rhodes est d’utiliser un excellent outil: FlatDoc créé par Rico Sta. Cruz.

FlatDoc va charger par ajax la documentation (README.md ou tout autre fichier de balisage), l'analyser et l'afficher avec tous les goodies et même un menu de barre latérale pour la navigation!

Il a intégré dans son api une méthode d'assistance pour charger des fichiers à partir de GitHub Repo Master (mais peut également charger n'importe où sur le Web).

Instructions

Commencez par copier le modèle html suivant dans votre fichier index.html dans votre branche gh-pages. Continue avec:

  • Remplacement de "USER" par votre nom d'utilisateur GitHub
  • Remplacement de "REPO" par votre nom de référentiel GitHub
  • Remplacer "Votre projet" par le nom de votre projet

dans le fichier. Essayez-le localement dans votre navigateur. Puis validez et appuyez sur les modifications. Maintenant, votre page github sera toujours mise à jour avec votre fichier README.md dans votre branche principale.

Si le thème par défaut ne vous satisfait pas, vous pouvez le reformater avec votre propre css.

2
Khalid Salomão

Une autre méthode qui fonctionne assez bien consiste à utiliser Ajax pour récupérer les documents à l'aide de l'API Github et d'un moteur de démarquage Javascript pour restituer le code HTML (comme l'a également suggéré Nathan).

  1. Utilisez l'API Github et JSONP pour récupérer le document à partir de Github
  2. Décoder le contenu base64 dans la réponse de l'API Github
  3. Rendre le markdown en utilisant un moteur de démarquage javascript
  4. Afficher le rendu HTML

Nathan a exprimé certaines inquiétudes quant aux performances, mais d'après mon expérience, le logiciel se charge apparemment instantanément, donc je ne pense pas que ce soit un problème.

L'avantage est qu'il est facile à configurer et qu'il mettra toujours à jour vos documents, même si vous modifiez simplement la réduction directement dans un navigateur sur github.

J'ai mis en place un exemple sur les pages Github à http://bradrhodes.github.io/GithubDocSync/ pour le voir fonctionner.

2
Brad Rhodes

Je souhaite également éditer des documents dans master et les publier dans gh-pages. J'aime garder les documents à jour avec le code source, ce qui semble être le meilleur moyen. C’est un travail en cours pour moi, mais j’ai pris le script de Cory comme point de départ et l’a un peu élargi pour le faire fonctionner dès qu’il existe une branche gh-pages avec _layouts (c’est-à-dire un jeky site). Il convertit les clôtures de style backtick (pour les blocs de code) qui fonctionnent bien dans la navigation dans les sources de github, mais pas dans les gh-pages. J'utilise un index.md avec une inclusion pour le projet README.md afin de pouvoir ajouter un en-tête et quelques autres décorations. Cette version gère également la documentation dans tous les répertoires imbriqués appelés "docs" que je trouve utiles dans un projet avec plusieurs modules (pas les sous-modules git, mais juste les sous-répertoires):

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

Une autre variante de l'original est qu'il définit une variable page.home dans toutes les pages. Cela peut être utilisé pour localiser le chemin relatif du répertoire racine, afin de localiser des ressources statiques comme css. Dans _layouts/.default.html j'ai:

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

De cette façon, je peux éditer le fichier css, construire le site jekyll localement et voir le résultat dans un navigateur sans devoir attendre que github le construise sur le serveur.

1
Dave Syer

Ce n'est pas difficile, deux copies et colle dans le terminal et vous êtes tous ensemble.

Jekyll vous permet d'importer votre fichier de démarquage, puis de le convertir en HTML. L'astuce consiste à importer votre README.md dans votre fichier index.md avec {% include_relative README.md %}. Voici comment nous pouvons faire cela: 

Cela vaut la peine de vérifier comment configurer un site Jekyll sur une base de barebones super sur github (c'est juste deux fichiers!)

La mise en place

Vous pouvez copier les deux fichiers et conserver votre page avec votre fichier Lisez-moi actuel en exécutant simplement cette configuration one time (copiez tout le bloc de code et passez-la au terminal):

# 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

Automatisation

Ensuite, nous devons simplement automatiser la tâche consistant à copier toutes les modifications de master dans la branche gh-pages avant chaque Push. Nous pouvons le faire en exécutant ce script (vous pouvez le copier et le coller dans le terminal)

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

Il créera un hook qui copiera toutes les modifications de la branche master dans gh-pages à chaque exécution de git Push. 

C'est tout. Terminé.

0
Marcelo Lazaroni

J'ai récemment créé un paquet gh-pages-generator pour résoudre ce problème, il génère un site de plusieurs pages utilisant plusieurs fichiers MD et un fichier de configuration.

Il met correctement à jour tous les liens entre les pages. Il est relativement facile d'intégrer dans CI les modifications apportées à la branche gh-pages.

Je l'utilise ici et ici .

0
esp