Is it possible to import code (not just entire files with the raw loader) and display in a doc block?

[unleashit]

I have some docs where currently I'm copy/pasting some Typescript types into md doc blocks. But as that's kind of tedious and error prone, I'm wondering if anyone has a solution that works with Docusaurus and mdx.

I've tried using the webpack raw loader as described in the docs: https://docusaurus.io/docs/markdown-features/react#importing-code-snippets. But this displays the full content of the file. What I'd like to be able to do is import and display individual exports like:

// source-file.ts
export type1 = number;
export type2 = string;

// other stuff...

Then in a Docusaurus mdx file have something like:

// some-doc.mdx
import CodeBlock from '@theme/CodeBlock';
import { type2 } from '!!raw-loader!@some-other-package.';

<CodeBlock>{type2}</CodeBlock>

But type2 ends up undefined as the raw loader must be preprocessing the entry file for @some-other-package as a string. I can make it somewhat work if I move type2 in it's own file and import it directly, but I'd really like to display only the raw type in my documentation (no import/export, comments, etc.). In the end I need to display exported code (types, functions, etc.) to the user something like:

API

type2

type2 = string;

(where the 3rd line is a string of the raw export, with no other code from the file)

I've googled around quite a bit. Am I missing an easy way to do this? Thanks!

[slorber]

you can approach this problem in multiple ways, such as creating your own raw loader that strips content outside string markers, or implementing a remark plugin.

---

Here's @jknoxville remark plugin that probably matches your need:
https://github.com/jknoxville/remark-code-snippets

Here's @christian-bromann remark plugin that fetches code blocks directly from a GitHub link
https://github.com/saucelabs/docusaurus-theme-github-codeblock

Not sure those solutions are compatible (yet?) with Docusaurus v3 but at least it can give you some inspiration.

---

Here's a tutorial on how to implement your own Webpack loader: https://webpack.js.org/contribute/writing-a-loader/

You could use this to create your own system that loads only a subset of the file, based on querystring markers

import { type2 } from '!!my-source-code-loader!./mySourceFile.tsx?marker=my-marker';

[christian-bromann]

Here's @christian-bromann remark plugin that fetches code blocks directly from a GitHub link

I continue to maintain this plugin in https://github.com/christian-bromann/docusaurus-theme-github-codeblock. We are using it in https://webdriver.io very successfully.

[unleashit]

Thanks, both of you! Neither of these are perfect, but good enough for this. And overall very impressive.

I've decided to go with remark-code-snippets for now, which at least so far seems to be working fine with the latest Docusaurus (3.1). The only drawback is I have to add hook comments to the source files and there is no easy way to remove the export declaration.

docusaurus-theme-github-codeblock looks great too. It solves the first problem but as it relies on line numbers I'm a bit worried this would get out of sync if I forgot to maintain in the docs.

I appreciate the advice on rolling my own loaders/plugins. Even if not worth the time for this project, I'm pretty new to MDX/Docusaurus and will take note for the future.