Docusaurus Theme GitHub Codeblock
A Docusaurus plugin that supports referencing code examples from public GitHub repositories.
Install
First, add the theme plugin to your dependencies:
npm install docusaurus-theme-github-codeblock
Usage
Add the theme plugin to your list of themes in the docusaurus.config.js
:
// ...
themes: [
'docusaurus-theme-github-codeblock'
],
// ...
themeConfig: {
// github codeblock theme configuration
codeblock: {
showGithubLink: true,
githubLinkLabel: 'View on GitHub',
showRunmeLink: false,
runmeLinkLabel: 'Checkout via Runme'
},
// ...
}
// ...
To reference GitHub snippets in your markdown, create code blocks with a reference
attached to the language meta string and put the link to your GitHub reference in the code block, e.g.:
```js reference
https://github.com/christian-bromann/docusaurus-theme-github-codeblock/blob/main/src/theme/ReferenceCodeBlock/index.tsx#L105-L108
```
You can also set a custom title:
```js reference title="Example"
https://github.com/christian-bromann/docusaurus-theme-github-codeblock/blob/main/src/theme/ReferenceCodeBlock/index.tsx#L105-L108
```
The plugin will download the code and display the desired lines:
Runme Support
In addition to providing a link to the GitHub source, you can also enable a Runme link to allow users to easily check-out the example markdown file with VS Code and run the code reference locally. To enable support, set showRunmeLink
to true
in your Docusaurus themeConfig
.
By default the Runme link is generated based on the repository and it will checkout a README.md
in the same directory as the file. For example using the example above, Runme will checkout the repository christian-bromann/docusaurus-theme-github-codeblock
and the file src/theme/ReferenceCodeBlock/README.md
.
If the markdown file you like the user to check-out is located in a different repository or path, you can define the repository
and fileToOpen
param of Runme link manually via, e.g.:
```js reference runmeRepository="git@github.com:christian-bromann/docusaurus-theme-github-codeblock.git" runmeFileToOpen="CONTRIBUTING.md"
https://github.com/christian-bromann/docusaurus-theme-github-codeblock/blob/main/src/theme/ReferenceCodeBlock/index.tsx#L105-L115
```
In case you have showRunmeLink
set for all code references, if you prefer to clone the reference using a Git HTTPS url, add useHTTPS
to the frontmatter:
```js reference useHTTPS
https://github.com/christian-bromann/docusaurus-theme-github-codeblock/blob/main/src/theme/ReferenceCodeBlock/index.tsx#L105-L108
```
Learn more about Runme in the project docs.
Options
This Docusaurus theme has the following options:
showGithubLink
If set to true
the link to the GitHub source of the reference is provided.
Type: boolean
Default: true
githubLinkLabel
Link text for GitHub link.
Type: string
Default: View on GitHub
showRunmeLink
If set to true
, a Runme link is provided. This property will be automatically set to false
if a mobile environment is detected given these environment don't support the vscode://
url schema.
Type: boolean
Default: true
runmeLinkLabel
Link text for Runme link.
Type: string
Default: Checkout via Runme
If you are interested in contributing to this project, see CONTRIBUTING.md.