docusaurus-theme-github-codeblock

Docusaurus Theme GitHub Codeblock !Test Changes
=================================

A Docusaurus plugin that supports referencing code examples from public GitHub repositories.

> Note: this theme plugin supports Docusaurus v2 and v3.

Install

First, add the theme plugin to your dependencies:

``sh
npm install docusaurus-theme-github-codeblock
`

Usage

Add the theme plugin to your list of themes in the docusaurus.config.js:

`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:

!Plugin Example

$3

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:

$3

If set to true the link to the GitHub source of the reference is provided.

__Type:__ boolean

__Default:__ true

$3

Link text for GitHub link.

__Type:__ string

__Default:__ View on GitHub

$3

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

$3

Link text for Runme link.

__Type:__ string

__Default:__ Checkout via Runme`

---

If you are interested in contributing to this project, see CONTRIBUTING.md.