Welcome to ghscard’s documentation!


ghscard

PyPI package version Supported Python versions npm package version Linux CI status GitHub stars

Summary

ghscard is a JavaScript widget to generate interactive GitHub user/repository/organization cards for static web pages (like GitHub pages/Read the Docs).


Quick Start

Generate card data files

Execute ghscard gen command to generate a GitHub user/organization/repository card data file.

$ ghscard gen thombashi -o data
[INFO] ghscard gen: written user data to 'data/thombashi.json'

$ ghscard gen Microsoft/TypeScript -o data
[INFO] ghscard gen: written repository data to 'data/Microsoft_TypeScript.json'

Add widget to an HTML file

Example
<!doctype html>
<html>
<body>
    <table border="0">
        <tr>
            <td>
                <div class='ghscard' src='data/thombashi.json'></div>
            </td>
            <td>
                <div class="ghscard" src="data/Microsoft_TypeScript.json"></div>
            </td>
        </tr>
    </table>

    <script src='//cdn.jsdelivr.net/gh/thombashi/ghscard@master/dist/ghscard.min.js'></script>
</body>
</html>

The above HTML rendered as follows:

Output
Click to navigate to the HTML page

CDN

Demo

CLI Tool Installation

Install ghscard CLI tool from PyPI via pip (Python package manager) command.

pip install ghscard

Dependencies

CLI Tool Dependencies

Usage

Create User/Organization Cards

  1. Generate a card data file

    Execute ghscard gen <user-name or organization-name>.

    $ ghscard gen thombashi -o data
[INFO] ghscard gen: written user data to 'data/thombashi.json'
  2. Add HTML tags to a HTML file
    <div class='ghscard' src='data/thombashi.json'></div>

<script src="//cdn.jsdelivr.net/gh/thombashi/ghscard@master/dist/ghscard.min.js"></script>
  3. Result

Create Repository Cards

  1. Generate a card data file

    Execute ghscard gen <user name>/<repository name>.

    $ ghscard gen Microsoft/TypeScript -o data
[INFO] ghscard gen: written repository data to 'data/Microsoft_TypeScript.json'
  2. Add HTML tags to a HTML file
    <div class="ghscard" src="data/Microsoft_TypeScript.json"></div>

<script src="//cdn.jsdelivr.net/gh/thombashi/ghscard@master/dist/ghscard.min.js"></script>
  3. Result

Card Configurations

card-style Attribute

Card size and display format change according to card-style attribute. card-style attribute takes one of the following values:

  • medium (default)

  • small

  • tiny

Examples

chart-display Attribute

Charts on repository cards can be changed visible or hidden by chart-display attribute value.

chart-display attribute

Value

Meaning

block

Display charts on cards.

none

NOT display charts on cards.

Default value differed by card-style attribute:

Default value of chart-display

card-style value

Default value

medium

block

small

block

tiny

none

Examples

topic-display Attribute

Topic labels repository cards can be changed visible or hidden by topic-display attribute value. Defaults to block.

topic-display attribute

Value

Meaning

block

Display topic labels on cards.

none

NOT display topic labels on cards.

Examples

Advanced Usage

GitHub API Token Setting

You can set GitHub API token via ghscard configure command to workaround GitHub API rate limit. You might exceed GitHub API rate limit when creating card data by ghscard gen command. Git Hub API token can create at https://github.com/settings/tokens/new

$ ghscard configure
GitHub API Personal Access Token: <token>
Output Directory Path [.]:

Tested environment

Tested Web Browsers

Web browser

Version

Google Chrome

57.0 or newer

Mozilla Firefox

52.0 or newer

Sponsors

Charles Becker (chasbecker)

Become a sponsor

Indices and tables

Indices and tables