@bcgov/gatsby-source-github-raw
v1.0.10
Published
Leverages the Github Contents API to convert files into transformable Gatsby Nodes
Downloads
27
Readme
Gatsby Source Github Raw
NOTE! Gatsby has introduced an api for Creating Remote File Nodes which is a more generic utility compared to this plugin. Please consider utilizing the native utilities before using this package!
A simplified way of leveraging the Github Contents Api
as Gatsby graphql nodes.
Features
- Implied Mime Types mime/media types are set based on file extensions when available
- Bind Properties you can bind properties that are 'attached' to the raw file node if needed
To Use
- Install
npm install --save @bcgov/gatsby-source-github-raw
- Add to your gatsby config
{
resolve: '@bcgov/gatsby-source-github-raw',
options: {
githubAccessToken: '...',
files: [
'https://github.com/foo/bar/blob/master/something.md'
]
}
}
Options
- githubAccessToken: this is the oauth access token, it will require read priviledges on a repo
- files: this is either a list of files [String], a list of objects, or a name of a resolved transformer json node type, or a function
Files Option
There are a few ways to pass in files
- as a simple array of strings
['https://github.com/foo/bar/blob/master/something.md', 'https://github.com/foo/bar/blob/master/something2.md']
- as an array of objects, this allows you to bind extra properties to each node
if you are binding properties, you need to ensure that the properties that you bind between files match the same schema since this process depends on gatsby's graphql type inferrence routine
[
{
url: 'https://github.com/foo/bar/blob/master/something.md'
labels: [ // labels will become a bound property that is available at node._xxboundProperties.labels
'cool',
'featured',
]
},
{
url: 'https://github.com/foo/bar/blob/master/something2.md',
labels: [ // labels will become a bound property that is available at node._xxboundProperties.labels
'featured',
]
}
]
- If there are many files you'd like to source, containing them all in the
gatsby-config.js
file is cumbersome. You may store your 'files config' into a json file and havegatsby-transformer-json
pick it up. The impliednodeType
that is created from the directory can be passed in as thefiles
option
foo.json
[
{
"url": "https://github.com/foo/bar/blob/master/something.md",
"labels": [
"cool",
"featured"
]
},
{
"url": "https://github.com/foo/bar/blob/master/something2.md",
"labels": [
"featured"
]
}
]
gatbsy-config
{
resolve: '@bcgov/gatsby-source-github-raw',
options: {
githubAccessToken: '...',
files: 'fooJson'
}
}
- Files as a function
/**
* fileCallback
* @param {Function} getNodes gatsby getNodes function in case you need it
* @returns {Array<String> | Array<Object>} a list of files in strings or objects
**/
const fileCallback = getNodes => {
// get nodes allows you to produce a set of urls based on your own conditions, for example if you
// had multiple json files that held url information that you wanted to normalize and use
return ['...list of files']
}
{
resolve: '@bcgov/gatsby-source-github-raw',
options: {
githubAccessToken: '...',
files: () => ['https://github.com/foo/bar/blob/master/blah.md']
}
}
Exceptions to applying bound properties
Because manifests can be passed in as plain js objects as well as loaded through the use of
@bcgov/gatsby-transformer-json
, to maintain consistency between these two possible sources, the following
properties are not usable within json
files that are leveraged as a source for files.
- internal
- id
- parent
- children
This is because these properties are default properties applied to any graphql node within gatsby.
Accessing Bound Properties
Bound Properties are accessed at node._xxboundProperties