saucelabs / docusaurus-theme-github-codeblock

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

Docusaurus Theme GitHub Codeblock

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

Note: this theme plugin requires Docusaurus v2

Install

First, add the theme plugin to your dependencies:

# NPM
npm install --save @saucelabs/theme-github-codeblock

# Yarn
yarn add @saucelabs/theme-github-codeblock

Usage

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

    // ...
    themes: [
        '@saucelabs/theme-github-codeblock'
    ],
    // ...

In order 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/saucelabs/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/saucelabs/docusaurus-theme-github-codeblock/blob/main/src/theme/ReferenceCodeBlock/index.tsx#L105-L108
```

The plugin will download the code and display the desired lines:

---

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

docusaurus-theme-github-codeblock's Issues

URL is not defined

It seems that building the Docusaurus page causes this error to be thrown.

Fetch code based on "Markers" rather than Line Numbers

Hi All,

Is there a possibility to include markers rather than line numbers while referencing the code snippets? For instance, here's an example code snippet:

# start_hello_function

def say_hello() -> str:
    return "hello world"

# end_hello_function

Here, start_hello_function and end_hello_function are the markers.

When this feature is included, we need not worry when there's additional code added as the code lying within the markers gets picked up when the changes are pushed.

Let me know what you think of it.
Thanks in advance!

Module not found: Error: Can't resolve 'url' in ...

Module not found: Error: Can't resolve 'url' in 'C:\Users\...\Documents\GitHub\...\node_modules\@saucelabs\theme-github-codeblock\build\theme\ReferenceCodeBlock'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "url": require.resolve("url/") }'
        - install 'url'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "url": false }
client (webpack 5.74.0) compiled with 1 error

Use `raw-loader` if Docusaurus is on the same repo

Leverage webpack raw-loader if docusaurus site is on same repo as source code, see for example v2.docusaurus.io/examples/markdownPageExample#import-code-block-from-source-code-file

[Documentation] Works without `@babel/plugin-transform-modules-commonjs`

I confirmed this package works without @babel/plugin-transform-modules-commonjs on Docusaurus 2.0.0-beta.3.

I'm not familiar with babel so I can’t describe how it works.

My environment:

 "dependencies": {
    "@docusaurus/core": "2.0.0-beta.3",
    "@docusaurus/plugin-pwa": "^2.0.0-beta.3",
    "@docusaurus/preset-classic": "2.0.0-beta.3",
    "@mdx-js/react": "^1.6.21",
    "@saucelabs/theme-github-codeblock": "^0.0.4",
    "@svgr/webpack": "^5.5.0",
    "clsx": "^1.1.1",
    "file-loader": "^6.2.0",
    "prism-react-renderer": "^1.2.1",
    "raw-loader": "^4.0.2",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "rehype-katex": "^5.0.0",
    "remark-custom-blocks": "^2.5.1",
    "remark-math": "^4.0.0",
    "url-loader": "^4.1.1"
  },

(sorry for bad English)

Run e2e tests

Ensure that the plugin integrates with the latest Docusarus v2 version by adding some e2e tests that renders the example page with an example code block.

Webpack error

Following the instructions provided in README.md causes webpack to throw the following error:

Module not found: Error: Can't resolve 'url' in '{projectPath}/node_modules/@saucelabs/theme-github-codeblock/build/theme/ReferenceCodeBlock'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "url": require.resolve("url/") }'
        - install 'url'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "url": false }
client (webpack 5.75.0) compiled with 1 error

Apparently in order to use this theme, you need to manually configure webpack to include or ignore that url module. This happens because this theme imports Node's url module, and this doesn't really fix it.

Based on that, I have a few suggestions to tackle this problem:

1. Document the steps to either polyfill or ignore the url module;
2. Provide a plugin that does that automatically;
3. Remove dependency on url module;

Deprecated dependencies and error

Hello! I would love to use this plugin, but hitting an UnhandledPromiseRejectionWarning error, which only pops up when using this plugin. It installs and does run perfectly, generates nicely, but the error keeps popping up and warns about deprecation. Some of the dependency packages have deprecations, maybe those need updates? Thanks!

(node:19682) UnhandledPromiseRejectionWarning: Error: Minified React error #301; visit https://reactjs.org/docs/error-decoder.html?invariant=301 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:19682) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 1)
(node:19682) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

I'm on Docusaurus v2 2.0.0-70.

Avoid render-side effect

There seem to be a render side-effect instead of firing the req in useEffect which is something to avoid in React. Using a small fetching lib (like mine slorber/react-async-hook) can prevent that.

Cache code in local storage

In order to save bandwith and not always fetch the same code all over again we should store everything in local storage.

Excessive CPU usage on certain pages

🐛 Bug Report

Description

Navigating to a page like https://docs.staging.saucelabs.net/testrunner-toolkit/configuration causes excessive CPU usage (150% in my case).
Other pages like https://docs.staging.saucelabs.net/testrunner-toolkit/running-tests do not exhibit such an issue.

I spoke to @spider-sauce earlier and he thinks it could be related to the github references plugin.

To Reproduce

Just navigate to a page like https://docs.staging.saucelabs.net/testrunner-toolkit/configuration and observe your browser process CPU usage.

Expected Behavior

CPU usage is constant after page has finished loading.

Actual Behavior

Excessive CPU usage after page has loaded and does not go down.

• OS: macOS Catalina
• Browser version: Firefox 84

Which language referece terms are supported?

The example shows js but what other languages are supported?

Can I use this to show a file which is text-based console output?

cannot resolve `url` with docusaurus 2.0.0-beta.18

Hey thanks for the repo, was looking to implement this but always nice when I don't have to.

Just tried using against latest 2.0.0-beta.18 of docusaurus v2.

Fails when loading a code block with the following.

Compiled with problems:

ERROR in ./node_modules/@saucelabs/theme-github-codeblock/build/theme/ReferenceCodeBlock/index.js 26:14-28

Module not found: Error: Can't resolve 'url' in '/Users/saf/dev/pactflow/docs.pactflow.io/website/node_modules/@saucelabs/theme-github-codeblock/build/theme/ReferenceCodeBlock'

BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
	- add a fallback 'resolve.fallback: { "url": require.resolve("url/") }'
	- install 'url'
If you don't want to include a polyfill, you can use an empty module like this:
	resolve.fallback: { "url": false }
	```
	
Removing the import from this line in the bundled output resolves it and it works fine

https://github.com/saucelabs/docusaurus-theme-github-codeblock/blob/3e94f0555f93f97fbb4db46673905dc6b9fe1635/src/theme/ReferenceCodeBlock/index.tsx#L1

Happy to submit a pull request

Fetch code examples at build time

Have a remark plugin fetch the actual code block content at build time instead of browse time (may make the build process longer and less reliable?).

This could be a theme options as some people might want to be able to fetch latest code examples from GitHub.

BaseUrl in Config

Would it be possible to specify a base URL for the code snippets in the config file?

I'd like to be able to specify the relevant commit in one place and have it apply to all of my code examples.

e.g.

https://github.com/saucelabs/sauce_bindings/commit/e9e56f0/

Support for Docusaurus 3.0

Docusaurus yesterday released 3.0 which includes support for react 18. I tried to update but the plugin doesn't work

Do you plan to release an update which will support docusuarus 3?

More useful title

Just the path to the file isn't very useful if it doesn't include which repo it is pulled from.

Can we have it use the full URL? I'm guessing it can't be an actual link.

At the very least maybe we can toggle it on/off or allow another argument?

Increase test coverage

We should ensure that our React components are well unit tested.