如何将文档与Github页面同步？ [英] How can I sync documentation with Github Pages?

问题描述

我有一个项目和几个人在一起，我们有一个 README.md 文件，其中有一堆GitHub Flavored Markdown，它在我们的GitHub页面上呈现。我们还建立了一个GitHub Pages分支，该分支在我们的GitHub组织的子域中托管，并使用当我们创建页面时，自动页面生成器 简单地加载到 README.md 文件中。但是，我注意到当我更新我们的 README.md 文件时，它不会更新项目页面。相反，我们必须进入GitHub设置选项卡并重新创建项目页面，然后重新加载 README.md 文件。

另外，阅读了 相对链接 在GitHub项目目录页面上的文档文件之间工作。我非常喜欢降价，因为它可以节省大量时间，无需手动编写所有HTML文档。然而，我想要的是能够有一个 README.md 文件，该文件能够包含相对于位于 docs / * .MD 。我希望有一个简单的解决方案，以便我的其他文档文件也可能包含在我的gh-pages分支中，并在我的GitHub页面子域中进行托管并呈现和/或为主题。

换句话说，我的问题是：

• 有没有办法让我的README.md文件自动更新Github页子域？
  
  
  
  
  • ：如果使用自动页面生成器，看起来没有答案。您必须前往repo的设置页面，并在每次更改时重新加载以更新它。
    
     
  
  


• 有没有办法让我的相关链接可以在我的GitHub页面上的README.md文件上工作，也许我以某种方式同步我的 / docs / *。md 到我的Github页面，并以某种方式呈现和/或主题他们？
  
  
  
  
  • ：从我写这个问题后学到的东西看来，这只能通过GitHub页面使用 静态网站生成器 ，比如ruby gem Jekyll ，并可能使用 GitHub支持的webhook ，它们在下面的评论中提到。我正在尝试寻找最佳解决方案。
    
    
    
  
  


• 更好的是，更简单的方法，我可以做到这一点，也许只有我的README.md和文档的一个副本在gh页面和我的主分支上使用，并使一切最简单？
  
  
  
  
  • ：看来这个几乎肯定是一个不行。我正在考虑在GitHub中内置什么来实现这一点的可能性。看来对这种事情的更好的支持可能会在未来被构建到GitHub Pages中，或者至少我绝对希望它会成为现实。
    
     
  
  我将发布一个解决方案，我可以利用这个解决方案事实上，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

$ p
$ $ p $ $ $ $ c> ---
layout：index
---


     你也需要打开 index.html 文件并进行以下更改：
     
     

     
     
     1. <删除呈现的HTML f从 README.md 文件中的降价。这通常在< section> 或< article> 标签之间。将此HTML替换为文本 {{content}} ，这将允许我们将此文件用作jekyll。我们将布局应用于的文件将放置在内容标签所在的位置。
     
     

     2. 找到项目页面主题的CSS。对于我来说，这是一个如下所示的行：

        
        
        

        


        
        
        

        这需要更改为
        
        

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


     
     
     3. 您的网站上存储的任何其他资产将用于此布局，还需要以。
     


     通过这样做，Jekyll将呈现降价文件作为 _layouts 目录中 index.html 布局的内容。为了使这个过程不仅仅是README.md文件自动化，还有其他文档可以在您的主分支中使用，我已经采取了以下步骤：



     创建包含以下内容的名为 post-commit 的文件：



      

      ＃！/ bin / bash 
      ### 
      ###提交到主分支后运行以下块
     ＃ ## 
      if [`git rev-parse --abbrev-ref HEAD` ==master];那么
      
     ＃布局前缀预先添加到同步的每个降价文件
      ########################### ######################################## 
      LAYOUT_PREFIX ='--- \r\\\
     layout：index\r\\\
      --- \r\\\
     \r\\\
     '
      
     ＃切换到gh-pages分支以与主控同步
      ############################################## ##################### 
      git checkout gh-pages 
      
     ＃将master中的README.md同步到index.md添加jekyll头文件
      ########################################### ######################## 
      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将master分支中的README.md同步到gh-pages中的index.md
      
     ＃同步docs / *目录中的降价文件
      ############################## ##################################### 
      git checkout master  -  docs 
     文件= docs / * 
     用于$文件中的文件
     用做
      echo -e $ LAYOUT_PREFIX | cat  - $ file>温度&& mv temp$ file
     完成
      
      git添加文档
      git commit -a -m将主文档中的文档同步到文档gh-pages目录
      
     ＃如果您想在本地提交主机时自动推送到
     ＃gh-pages分支，则取消注释以下推送。 
     ＃这有点极端。小心使用！ 
      ############################################## ##################### 
     ＃git push origin gh-pages 
      
     ＃最后，切换回主分支，出口区块
      git checkout master 
      fi 
       

     编辑： strong>我更新了 README.md 文件的上述脚本和 docs / * 中的降价，以便同时使用相同的布局文件。这是一个比以前更好的设置。这个脚本进入你的 .git / hooks / 目录。 bash必须在你的路径中。

     
     
     

     使用以下命令创建文件 _config.yml
     
     

       markdown：redcarpet 
     路径：http://username.github.io/reponame 
       

     上面的脚本还会同步<$ c $ 目录中找到的降价文件c> master 分支，以便它们可以在GitHub Pages网站上查看。如果您包含以下jQuery函数以便从 gh-pages 中的锚点去除 .md 扩展名， code>分支。您可以将以下脚本添加到 _layouts 目录中的 index.html ：

       $（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]）; 
     }）; 
     }）; 
       

     编辑：我更改了上述代码库中的代码，快速和肮脏的方式来做到这一点，但如果你知道我的意思，它将无法正常工作。例如，降价文件 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 ，其中 项目页面 ，如果您想了解所有这些功能如何协同工作。

     
     

     I have a project together with several people and we have a README.md file with a bunch of GitHub Flavored Markdown that is rendered on our GitHub page. We also set up a GitHub Pages branch which is hosted under our GitHub Organization's subdomain, and used the Automatic Page Generator simply loading in our README.md file when we created our page. However, I notice that when I update our README.md file, it does not update the project page. Instead, we must go to the GitHub settings tab and recreate the project page, reloading the README.md file when we do it.

     Also, after reading about relative linking working between documentation files on the GitHub project directory pages. I very much like the markdown as it saves tons of time from having to write all the HTML out by hand for our documentation. What I would like however is to be able to have one README.md file which is able to include relative links to other documentation files located at docs/*.md. I was hoping there was an easy solution so that my other documentation files might also be included in my gh-pages branch and be hosted under my GitHub Pages subdomain and be rendered and/or themed.

     In other words, my questions are:

     • Is there a way to have my README.md file automatically update on my Github Page subdomain?
       • [ EDIT ] : No appears to be the answer if using the Automatic Page Generator. You must go to the settings page for the repo and reload it every time there is a change in order to update it.
          
     • Is there a way I can have my relative links to my documentation on my README.md file work on my Github Pages, perhaps my somehow syncing my /docs/*.md to my Github Pages and somehow rendering and/or theming them?
       • [ EDIT ] : From what I've learned since writing this question it appears that this is only possible on GitHub pages through the use of a static site generator like the ruby gem Jekyll and probably some uses of the webhooks supported by GitHub that are mentioned in the comments below. I am trying currently trying to find an optimal solution.
          
     • Better yet, is there an even easier way I can do this and perhaps have just one copy of my README.md and documentation that is used on both gh-pages and my main branch and makes everything easiest?
       • [ EDIT ] : It seems this one is almost definitely a no. I was thinking about the possibility of something built into GitHub to allow this. It seems that better support for this kind of thing may could be built into GitHub Pages in the future, or at least I definitely hope it will be.
          

     解决方案

     I am going to post a solution that I setup that takes advantage of the fact that GitHub Pages uses Jekyll already using the Automatic Page Generator.

     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. Prepend the following text to index.md

      

     ---
     layout: index
     ---
     

     You also need to open the index.html file and make the following changes:

     1. Remove the rendered HTML from the markdown in your README.md file. This is usually between <section> or <article> tags. Replace this HTML with the text {{ content }} this will allow us to use this file as a jekyll. The file we apply the layout to will be placed where the content tag is.

     2. Locate the CSS for your project page theme. for me this was a line like the following:

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

        This needs to be changed to

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

     3. Any other assets stored on your site that will be used in this layout will also need to be prefixed with {{ site.path }}.

     By doing this, Jekyll will render the markdown file as the content of the index.html layout in the _layouts directory. In order to automate this process for not just the README.md file, but also other docs you may have in your master branch, I have taken the following steps:

     Created the file called post-commit containing the following:

      

     #!/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: I updated the above script for both the README.md file and the markdown in docs/* to both use the same layout file. This is a much better setup than what I had before. This script goes in your .git/hooks/ directory. bash must be in your path.

     Create the file _config.yml with the following

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

     The above script also syncs markdown files found in the docs/* directory of the master branch, in order that they may be viewed on the GitHub Pages site as well. Relative linking to these documents works if you include the following jQuery function in order to strip the .md extension from the anchors on the gh-pages branch. You can add the following script to index.html in the _layouts directory:

     $(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: I changed the code above in my repository, this was a quick and dirty way to do this, but it won't work right in all cases if you know what I mean.. For example, the markdown file company.mdata.md would not be processed correctly. To fix this I updated this to the following script which more carefully checks out the href and removes the extension if found. I also made the script more generic, allowing it to be used to remove other extensions by changing the ext variable. Here is the 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));
         });
     });
     

     I setup an example repo at CoryG89/docsync, which has a project page here, if you'd like to see how all this works together.

     这篇关于如何将文档与Github页面同步？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！