Welcome to ghscard’s documentation!¶
ghscard¶
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¶
CLI Tool Installation¶
Install ghscard
CLI tool from PyPI via
pip (Python package manager) command.
pip install ghscard
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:
CDN¶
- Version specific
https://cdn.jsdelivr.net/npm/ghscard@<version>/dist/ghscard.min.js
e.g. https://cdn.jsdelivr.net/npm/ghscard@0.4.1/dist/ghscard.min.js
Usage¶
Create User/Organization Cards¶
- 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'
- 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>
- Result
Create Repository Cards¶
- 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'
- 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>
- 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
chart-display
Attribute¶
Charts on repository cards can be changed visible or hidden by chart-display
attribute value.
Value |
Meaning |
---|---|
|
Display charts on cards. |
|
NOT display charts on cards. |
Default value differed by card-style
attribute:
|
Default value |
---|---|
|
|
|
|
|
|
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 [.]: