Customization use-cases

[slorber]

Hello everyone,

For the v2.0 launch of Docusaurus, one major goal is to make it easier to customize your site (see the blog post).

For that reason, I'd like to gather an exhaustive list of all the customization use-cases you have.

Goals

We want to ensure such customizations can be added in a robust way:

• More granular theme components: reduce API surface you copy when using docusaurus swizzle
• New swizzle --wrap command ([2.0] RFC: docusaurus swizzle --wrap/copy #5380)
• Provide stable CSS classes that you can confidently target with custom CSS
• Explicit TypeScript API surface for theme components
• Make the public API surface clearer: what is safe to customize, what is more, likely to break on upgrades
• Reduce and document better the breaking changes
• Better guides on how to customize a Docusaurus site

Instructions

• Report each use case as a separate discussion thread (in this issue/discussion)
• If your use-case is already mentioned by someone else's thread, please post in that thread
• I may edit threads/discussions to keep things readable
• For the most complex use-cases, we may create dedicated issues

Please describe the desired outcome of this customization (avoid the XY problem):

• Good outcome description: "I want to add a comment system at the end of each blog post"
• Bad outcome description: "I tried to swizzle component X and Y because I want to add some code in this place but it is not good enough for my use-case (that I never describe) because Z"

Please include all the info you can:

• Screenshots
• Public source code | private code sample
• Public site URL

Here's an example template you can use:

# Customization feature name

<!--
TODO 
Customization description
-->

## Infos

- Site source code: <!-- TODO -->
- Site URL: <!--  TODO -->
- Feature URL: <!--  TODO -->

## Screenshots

<!-- 
TODO add feature screenshots here so that it's easy to understand what you are talking about
-->

## Implementation

<!-- 
TODO 
Describe how you implemented this feature and why the implementation is not ideal.

If you couldn't build it, tell us why.

Add relevant GitHub code links, and code samples here 
-->

---

I'll start a few example threads.

Thanks, everyone!

[slorber]

Resolved: adding a doc item footer widget will be much easier since the doc item has been split into much smaller components

[Josh-Cena]

Re-implement blog list page as card cascade view

The blog list page by default displays posts as a list, with IMO very low page space usage efficiency. I customized it into a card cascade (I plan to implement lazy-loading in the future when the number of posts increases), and this makes me able to display much more information per unit space.

Infos

• Site source code: https://github.com/Josh-Cena/Personal-page
• Site URL: https://joshcena.com
• Site URL: https://joshcena.com/blog

Screenshots

Implementation

I swizzled BlogListPage, BlogPostItem, and BlogTagsPostsPage, just so that I can add my card container and render non-post-page post items as cards.

[slorber]

Improve and customize the blog sidebar

The blog sidebar only display a list of blog posts. We should be able to add more useful information here:

• Display list of featured blog posts
• Display tags
• Display authors
• Display available feed icons
• Display random text / links

Infos

• Site source code: https://github.com/temporalio/documentation
• Site URL: https://docs.temporal.io
• Feature URL: https://docs.temporal.io/blog

Screenshots

Implementation

Requires swizzling multiple components in https://github.com/temporalio/documentation/tree/master/src/theme

=> large API surface to maintain over time

Also, swizzled components are modified to include hardcoded data, because Docusaurus does not provide the relevant data as sidebar props

[slorber]

We have a dedicated issue to track the blog sidebar customizations: #5461

(please don't comment here, use the dedicated issue)

[mlynch]

Navbar should support "multi-tenant" sites

Customizing the header is a big one for us. Our platform has multiple sub-libraries that users install, so for our documentation, we have a single docusaurus site for each because we struggled to use the versioning system for multiple libraries. We then run those sites on separate paths ("multi-tenant"). However, docusaurus's theme (understandably) expects to be single tenant. So, we needed to modify the navbar to let the user go back to the root site. You can see that here: https://ionic.io/docs where /docs is a single docusaurus site, then /docs/windows, for example, is a separate one and it shows a back button.

I was able to do this by modifying the Logo component and showing a back arrow if not on the root path. However, that component was not available in the swizzle command, so I just copied it over.

[slorber]

Thanks

we have a single docusaurus site for each because we struggled to use the versioning system for multiple libraries

You could eventually make all libs live in a single site, but I'm not sure it would be a good idea.

Splitting into multiple smaller sites is useful for reducing build/deploy times and it's even a pattern I plan to document better in the future. You can share some config, CSS, and customizations across individual sites to make it more sustainable.

However, docusaurus's theme (understandably) expects to be single tenant. So, we needed to modify the navbar to let the user go back to the root site.

That's true today, but we'll make this easier in the future with #4389:

• Allow navbar items to be rendered only for certain paths (ie /docs/windows)
• Allow using custom navbar item types (ie backButton)

Do you think the issue above would solve all your use cases?

I suggest moving the next comments to the existing issue #4389 (unless you have another useful comment to add not covered by the "activation strategies" and "custom navbar item types")

[sivaraam]

Some reliable style customizations

For our site, we need a few style customizations which I believe could be achieved just using custom CSS if reliable class names are available for customization. I think the difficulty right now is that the class names that could be customized aren't easily identifiable [related discussion]. If I understand correctly, that's being worked upon in #6116 which is nice to see!

I'm sharing the customizations that we find necessary here hoping it would be useful:

1. Custom navigation bar styles. Particularly, customizing the height and background.
2. Custom text colors on navigation, header bar and links
3. Custom inidicator styIe to highlight current section in right side section navigation bar
4. Custom styles for block quotes, mono space highlights and table
5. Some similar customizations in dark theme. Like navigation panel background, highlighted text colour, table borders and block quote borders.

Let me know in case you need more information regarding any of the above.

Screenshots

Light theme full page screenshot

Dark theme full page screenshot

Implementation

Achieved the customizations via hacky CSS that do the trick for the given Docusaurus version but break after a Docusaurus upgrade. The version we use now and the one in which the customizations work is one of the alphas and the version in which some customizations break is the latest beta. We haven't gotten around to upgrading to the latest beta for now as we're sort of waiting it out to see if the stable version comes out soon 🤞🏼 😉 . But we do plan on upgrading before releasing the site for use withing the org.

I could share the custom CSS here in case that would be helpful.

[antonk52]

Customisations to DocContent

This opens opportunities like having an in-page editor which can be primarily useful for non VCS users. however, even for developers that do not have a project checked out would need to do extra steps. Editing becomes easier with recent github workspaces feature, but not all projects are hosted on github 🙂. If your VCS hosting provides an API to create PRs "on the fly", in-page editor is a handy feature that helps keeping documentation up to date.

From discussion

[antonk52]

Unfortunately, I cannot share any more details.

[slorber]

@antonk52 does it work for your use-case if we add a global wrapper around all MDX content (not just docs)?

#6842

I'd like to avoid creating one special wrapper per theme plugin page (x3). We also want to add an API that tells which plugin is currently active so you could easily add if/else logic in this component later.

In the meantime maybe pathname.startsWith("/docs") can be good enough?

[slorber]

Also looks like a similar use-case to @roydukkey in #5468 (comment)

If we also add a useFrontMatter hook it means you'd also be able to turn on/off your codespace logic based on doc frontmatter with great flexibility

[antonk52]

Thank you for the update.

Please correct me if I am wrong. I have built docusaurus website using the branch from the linked PR and the newly added MDXContent is first one(yellow) in the react tree

react tree screenshot

If the above is correct, unfortunately this change does not solve our issue as all our logic lives in DocItem that we have to sync with the one from docusaurus. If I understand it correctly using a wrapper component for MDXContent is less useful for us as still won't be able to affect the components located the closest to the content from a mdx file and we still would have to overwrite DocItem for it.

[slorber]

@antonk52 you are totally right the MDXContent item is not applied at the correct place, I'll update the PR right now.
Let's move the discussion on the PR itself for technical details and review

[roydukkey]

Add a doc item header component

Websites might want to enhance the default header with extra widgets.

Common needs might be:

• A published/updated date
• A share link
• A category name

Infos

A) Published/Updated Date

• Site source code: https://github.com/Josh-Cena/Josh-Cena.github.io/blob/04ba69169f6181bd623185bb8f9be1070a6fdb4c/docs/Science/1-cavalieri.mdx?plain=1#L11-L13
• Site URL: https://joshcena.com/
• Feature URL: https://joshcena.com/docs/Science/cavalieri/

B) Category Name

• Site source code: https://github.com/roydukkey/sass-fairy/blob/e8b470429d386ccdd18040339e01343471495bce/website/src/theme/Heading.tsx
• Site URL: http://sass-fairy.com/
• Feature URL: https://sass-fairy.com/api/break/helpers/annotate

Screenshots

A

B

Implementation

A

This requires a MDX component to be explicitly used on ever doc page. This is not ideal because someone could easily forget to add the MDX component to new doc pages, and ever doc page would need to be touched in the event the component's requirements change.

B

This wraps a theme component that is no longer exposed. Since 2.0.0-beta.15 there is currently no way to reliably duplicate the behavior.

Suggestion

Ideally, the solution would allow you to wrap a component that would allow someone to insert content before of after the main H1 on the doc item.

[roydukkey]

@slorber How would differentiate between all of these H1s?

---
title: Heading 1 (A)
---

# Heading 1 (B)

## Heading 2

# Heading 1 (C)

The only one I really want to target is the title (A). This is what I was trying to explain here #6283

[Josh-Cena]

@roydukkey You should not have multiple h1 headings in a document: every page should only have one h1 heading.

[slorber]

If a markdown h1 heading is used in the doc, we don't insert the frontmatter heading in the doc. Afaik in this case the frontmatter title is only used for page title (SEO) and not actually displayed.

And as @Josh-Cena said you shouldn't do C) in the first place 🤷‍♂️

At most, <Heading as="h1">text</Heading> should be used once in your doc so you should be able to customize it

[roydukkey]

Gotcha.

[razzeee]

I'm looking for a way to always have an image above the heading and the anchor should scroll to a position that includes the image. It should also still show up in the navigation on the right.

So far I could not figure out how to do this.

[urish]

Different og:image (social sharing image) per page

I'd like to be able to provide a different og:image value, based on the URL of the page. Right now, I can only find a way to configure a site-wide og:image, by setting the image property of themeConfig.

Infos

• Site source code: https://github.com/wokwi/wokwi-docs
• Site URL: https://docs.wokwi.com

Implementation

After spending two hours digging through the source code of storybook and looking at the available options for swizzling, it seems that the best workaround would be to use a Cloudflare worker in front of the docs site. The worker will replace the value of the "og:image" property with a different value, based on the page's URL.

Ideally, I'd like to have a way to do this from within Docusaurus: either by defining a template string, with a placeholder for the URL of the current page, or by providing a function that gets the URL of the current page and returns the respective og:image.

[urish]

And here's the Cloudflare worker implementation of this feature: wokwi/wokwi-docs@547eb7f

[slorber]

👍 we definitively want to support that use-case @urish and even have an old issue for that: #2968

Your workaround implementation works but it may not be the simplest to rely on page paths 🤪
https://thumbs.wokwi.com/docs/getting-started/wokwi-club/thumbnail.png

Cloudflare Workers is a nice workaround but not every site have access to an edge processing to handle that.
(ie GitHub Pages, although it's possible to add Cloudflare on top).

We'll look into providing that, but also support generating those images during the build, providing the right infos in a node callback.

In the meantime, I'm thinking of adding a dedicated theme component to declare social card metadata so that you can at least swizzle that logic and override it.

[urish]

Thanks Sebastian! I ended up ditching the Cloudflare implementation in favor of build-time processing:

https://github.com/wokwi/wokwi-docs/blob/f4d26dc89bb7b5043f0824393f2a1d60c60613a2/scripts/thumb-urls.js#L20-L23

With the Cloudflare version, users would occasionally get a broken, unstyled page. This was usually on first page load, and tricky to debug, so I ended up doing the image URL replacement at build time.

[jaredcbaum]

Split up DocItem component

We would like to separate the sidebar and navbar/content into separate sections on the page. Currently the navbar stretches all the way across. It is fairly easy to remove from the layout component, but in order to add it above the page content there are a few hurdles to jump through. If the DocItem component was split up similarly to how the DocPage is, with the layout as a separate subcomponent, then it would easier to add the navbar in a custom place.

I think this would also benefit other sites since it would allow better customization of the version banner, breadcrumbs, version badge, pagination, footer, and table of contents.

Here is an example of the layout

[jaredcbaum]

Here's a repo where I've done the minimum amount to create such a layout. Here is where the navbar is added.

Note how the entire DocItem component must be ejected, which isn't ideal.

[jaredcbaum]

Upon further investigations, it's probably better to swizzle the DocPage/Layout/Main and insert the Navbar component there if that's the only thing being added. For our purposes we also need to add a Code Sandbox in DocItem, so it makes sense to add the navbar there as well and not swizzle DocPage

[slorber]

We have split the DocItem component into much smaller components. Feel free to provide feedback but I consider this as resolved

I'm not sure what you mean by inserting the Navbar component there.

[jaredcbaum]

Expose metadata outside of DocItem

For our specific use case, we need access to the editUrl inside the table of contents component. As of now, this requires swizzling the DocItem component to add an extra prop to table of contents. If metadata was available via hook, then it would eliminate the need for unnecessary swizzling.

How we're doing it in DocItem component
How we're doing it in TOC component

I believe this would also benefit others trying to customize a Docusaurus site because there are plenty more metadata props besides editUrl that could be available.

[Josh-Cena]

This should be fixable by #6885

We would expose the useful metadata as a context to avoid prop drilling.

[LunaticMuch]

How we're doing it in TOC component

This link is broken

[marikaner]

Navigate through multiple (versioned) flavors of a product

We have one product that is available in Java and JavaScript. We have some common documentation for both languages as well as major parts that are relevant for only one of the languages.
We wanted to have a clean navbar that makes it clear which parts we are currently looking at (common overview, Java, JS).
When navigating through the Java parts, I don't need to see the version dropdown for JS and vice versa. In the overview, I probably don't want to see either of the dropdowns.

Infos

• Site source code: SAP/cloud-sdk
• Site URL: https://sap.github.io/cloud-sdk/
• Feature URL: basically all pages

Screenshots

Navbar for JS:

=> JS version dropdown shown
=> other JS related navbar items shown

Navbar for Java (versioning soon to come):

=> JS version dropdown not shown

Navbar for common pages:

=> no version dropdown

Note, that the three navbar items "Overview", "Java" and "JavaScript" are always shown.

Implementation

All our changes were possible with merely wrapping.

DocVersionDropdownNavBarItem

We adjusted the DocVersionDropdownNavBarItem to only show for the respective docsPluginId. I would have expected this by default when I have multiple content docs. I think it would be nice if this could be configured without customizing.

DropdownNavbarItem

We adjusted the DropdownNavbarItem to only show for the respective docsPluginId and to only show data related to a specific version of the current implementation. This second part could probably have been implemented differently, but as we already had to swizzle it, we decided to make it part of the dropdown as this required less changes in general.

NavbarNavLink

We also wrapped NavbarNavLink and I do not fully understand why this is necessary, but we couldn't get the version dropdown to show when expected without this.

What was not possible

We struggled with the following:

1. Go to JavaScript
2. Switch to version 1
3. Go to Overview (next to Java and JavaScript)
4. Go back to JavaScript

=> Version is set back to version 2, because it is not possible to set the path for a NavBarNavLink dynamically. It would be more intuitive to keep it at version 1 in my opinion. We were not able to achieve this.

[pelikhan]

Resizable split panes in docs

The goal is to load a code editor in a column on the right (iframe in this case) and allow the user to try out snippets in that editor. Currently done by using the Root element but this means that the menu bar does not extend the whole screen. It would be nice to be able to swizzle layout.

Infos

• Site source code: https://github.com/microsoft/devicescript/blob/main/website/src/contexts/SplitDevTools.jsx
• Site URL: https://microsoft.github.io/devicescript/intro
• Feature URL: click on run on that page

Screenshots

Implementation

Using Root element, used React-split-pane to split the entire page on demand.

[slorber]

It would be nice to be able to swizzle layout.

Maybe you can try swizzling DocRoot or DocRoot/Layout instead?

Note sure it's open-souce but I've seen some existing Docusaurus sites that achieved somehow quite similar layouts: https://outerbounds.com/docs/chunk-df/

More info here: https://outerbounds.com/blog/technical-docs-with-docusaurus-and-notebooks/ or maybe @hamelsmu can give more details

[pelikhan]

This blog post is a great read!

[johnnyreilly]

I did my first ever swizzle this week (so I could use fetchpriority on my Largest Contentful Paint) - it's a really cool mechanism! I like that you can do it on a component by component basis

[pelikhan]

Custom button in rendered snippets

We would like to add more buttons next to word wrap, copy. For example a button that launches a codesandbox workspace.

Infos

No implementation

Implementation

One would have to eject CodeBlock... which is kind of ugly. It would be nice to move section into a swizzable component

docusaurus/packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/String.tsx

Line 105 in 9473508

<CopyButton className={styles.codeButton} code={code} />

[slorber]

Yes we don't make it easy atm 😓 related to #8457 asking for a download code button

[pelikhan]

Voted for that swizzle.

[stanch]

Wider table of contents on non-doc pages

Currently the layout of the non-doc pages is hardcoded with col--8 for content and col--2 for the TOC, but this makes the TOC much narrower than it’s on the doc pages (at least on my screen).

I’ve changed this with npm run swizzle @docusaurus/theme-classic MDXPage -- --eject --danger, but it would be nice to either get matching layouts, or at least have an easier way to tweak this without an unsafe swizzle.