Docusaurus Theme GitHub Codeblock

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:

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="[email protected]: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.