npm:hexo-generator-github

README

hexo-generator-github

A generator used to generate page for Hexo from your exists Github project file.

Installation

$ npm install hexo-generator-github --save

Usage

hexo-generator-github can be used as helper/generator/console plugin. hexo server and hexo generate will call the generator of this plugin; A console command is provided to run this generator.

$ hexo github [-r --replace]

If -r or --replace option assigned, the generator will call github api and replace the existing github contents cache.

Config

github:
  debug: true # enable debug to log github api request/response
  user: Jamling # your github user name
  timeout: 60000 # set the github api request timeout
  token: your_token # enable Authorization for github api request, the api request limit will grow up from 60 to 5000
  cache_dir: gh_cache # the response of github api will store under the directory.
  repos: # request following repositories, otherwise, all repositories (limit 100) of user will be requested.
    - SmartIM4Eclipse
    - SmartIM4IntelliJ
    - hexo-theme-nova
    - hexo-generator-i18n
    - hexo-generator-github
    - hexo-generator-index2
    - hexo-filter-highlight
    - Android-ORM
    - eclipse-explorer
    - QuickAF
  navs: # project page left default nav menu, you can config for each project in ${blog}/_data/projects.yml
    overview: index.html
    index: index.html
    start: start.html
    release: release.html
    download: download.html
    userguide: userguide.html
    change: change.html

debug: Whether print debug info
cache_dir: Github response cache dir, you can run hexo github -r to remove all cache or remove files in cache manually to refresh cache again
user: Github user name
repos: Result repositories, return all(limit 100) repositories of user if undefined in _config.yml
token: See to generate token to grown up github api request limitation

Front-matter

A gh front-matter is nessary in your page to generate github response.

gh.user the github user, default is github.user in _config.yml, see gh_opts
gh.repo the github repo, default is fetched from url, see gh_opts
gh.type
- get_repos get repositories from github, see gh_repos
- get_contents get markdown file under repository, see gh_contents
- get_releases get releases under repository, see gh_releases

Helpers

gh_opts

Return full page.gh. If no user assigned in page gh front-matter, the user will set from hexo.config.github.user If no repo assigned in page gh front-matter, the repo will set from page.path Sample:

page.path = p/Android-ORM/ => gh.repo = Android-ORM
page.path = en/p/Android-ORM/ => gh.repo = Android-ORM (The hexo.config.language must contains en in _config.yml)

gh_repos

Return array of github user's repos

  {%- for p in gh_repos() %}
    <!--<div class="col-sx-6 col-sm-6 col-md-6 col-lg-6">-->
      <div class="panel panel-default project">
        <div class="panel-heading">
          <h3>
            <span class="icon nova-repo black-text"></span>
            <a href="./{{ p.name }}" target="_blank" title="{{p.name}}"> {{ p.name }}</a>
            <a href="https://github.com/{{p.owner.login}}/{{p.name}}" target="_blank" title="view on github"><span aria-hidden="true" class="icon nova-github right black-text"></span></a>
          </h3>
        </div>
        <div class="panel-body">
          <p>{{ p.description }}</p>
        </div>
        <div class="panel-footer">
          <iframe src="https://ghbtns.com/github-btn.html?user={{p.owner.login}}&repo={{p.name}}&&type=star&count=true" class="github-iframe" height="20" width="110"></iframe>
          <iframe src="https://ghbtns.com/github-btn.html?user={{p.owner.login}}&repo={{p.name}}&&type=fork&count=true" class="github-iframe" height="20" width="110"></iframe>
        </div>
      </div>
    <!--</div>-->
  {% endfor %}

Option	Description	Default
`user`	Github user	`config.github.user`

gh_contents

Return github (markdown file) contents of repository

{% set page.content = gh_contents() %}

So the page content will be replaced of content of github.

Option	Description	Default
`user`	Github user	`config.github.user`
`repo`	Github repo	`page.gh.repo`
`path`	Github content path	README
`ref`	Github reference	master

gh_releases

Return array of github repo releases

{% for p in gh_releases() %}
<div class="release">
  <div class="header">
    <a href="{{p.html_url}}">{{p.name}}</a>
    <a href="{{p.author.html_url}}">{{p.author.login}}</a> released this on {{gh_time(p.published_at)}}
  </div>
  <div class="markdown-body">
    {{markdown(p.body)}}
  </div>
  <h2 class="release-downloads-header">Downloads</h2>
  <ul class="release-downloads">
    {% for d in p.assets %}
    <li><a href="{{d.browser_download_url}}">
      <strong>{{d.name}}</strong> ({{d.download_count}} downloads)</a>
    </li>
    {%- endfor %}
  </ul>
</div>
{% endfor %}

Option	Description	Default
`user`	Github user	`config.github.user`
`repo`	Github repo	`page.gh.repo`

gh_edit_link

Return edit link string of github contents

{{ gh_edit_link() }}

gh_aside_nav

Return project content navigator tree

      $('#project_tree').treeview({
        enableLinks: true,
        color: '#428bca',
        expandIcon: 'icon nova-arrow-right2',
        collapseIcon: 'icon nova-arrow-down2',
        //levels: 3,
        //node-icon: '',
        //selectedColor: '#ff0000',
        onNodeSelected: function(event, data) {
          if (data.state.selected){
            return;
          }
        },
        data: {{ gh_aside_nav({parent_color:'#337ab7'}) }}
      });

Option	Description	Default
`user`	Github user	`config.github.user`
`repo`	Github repo	`page.gh.repo`
`path`	Github content path	README
`ref`	Github reference	master

Reference

Github Developer: see more properties of github response.
hexo-theme-nova: the nova theme used this plugin to generate project pages.

License

MIT

Usage no npm install needed!