本文介绍了如何将文档与Github页面同步?的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!

问题描述

我有一个项目和几个人在一起,我们有一个中的锚点去除 .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));
});
});

我在,其中,如果您想了解所有这些功能如何协同工作。


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页面同步?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持!

07-29 19:25
查看更多