Include "dynamic content" list into a page

[tgrall]

Hello,

TLTR;
I would like to include in a page/mdx a list of content based on their "keywords" (or custom attribute}
What is the best way to achieve this?

Content

1. My document site contains various types of content: simple doc, tutorials, simple application
2. I would like to be able to create a component that allows me to include the list of this content in a page.

For example, if I have a page that contains content about "Java Development", I would like to add a dynamic list to show "all the java tutorials", same for "python tutorials" and a generic page that shows "all tutorials"

what is the best way to achieve this?

[slorber]

Do you mean a tagging system?
For example here's the page of a blog tag: https://v2.docusaurus.io/blog/tags/recap

There's an issue to add this to docs as well:
#3434

[tobiasbueschel]

Adding to this thread, I'm looking for something similar to create dynamic readmes that show:

• List of pages that were added / modified in the last 7 days
• Any open to-dos (i.e. markdown checkbox items that are not marked as completed)

[muuki88]

We are thinking about migrating from Jekyll to docusaurus and are searching for a similar solution.

Our use case is the following. There are couple of different layouts, which identify certain pages. We use this to generate overview pages. Jekyll enables this by having global site.pages variables. The page variable contains the (front matter) meta data.

Here you can see one of those pages:

• https://github.com/prebid/prebid.github.io/blob/5d9377d92983ca176795f705847e7b5a67f9c4fc/download.md?plain=1#L58-L61
• https://github.com/prebid/prebid.github.io/blob/5d9377d92983ca176795f705847e7b5a67f9c4fc/download.md?plain=1#L70-L80

I'm unsure how this would work in docusaurus though. A very naive implementation would be to have access to a site variable, which is generated during build and used through out.

import site from '~/global/site'; // I don't care what the path looks like

# Cool page with MDX

{site.pages
  .filter(page => page.layout === 'foo')
  .forEach(page => (<div>{page.title}</div>)
}

Probably this is invalid MDX, because I have not used it a lot, but you get the gist. The same would be possible in a component of course.

Huge drawback is that we would end up with a possibly gigantic site.js file.

[slorber]

Having a gigantic site.js bundle is not a good idea for Docusaurus.

Unlike Jekyll it has to hydrate React on the frontend and adding too much to the JS will slow down hydration, leading to event listeners being attached with a delay, leading to a confusing ux where buttons wouldn't click.

We have an undocumented allContentLoaded plug-in lifecycle that you could use to pick/format the minimal data you need to inject it into a page. I may refactor the public api later but the feature is unlikely to disappear.

Unfortunately it doesn't allow injecting into an existing page, only create a new page.

React Server Components cous make all this easier and more flexible

[muuki88]

Having a gigantic site.js bundle is not a good idea for Docusaurus.

Yeah. That's what I thought as well.

We have an undocumented allContentLoaded plug-in lifecycle that you could use to pick/format the minimal data you need to inject it into a page. I may refactor the public api later but the feature is unlikely to disappear.

I started trying to build a plugin that generates a toc.js for a specific folder and emits it at a specific place to limit the size and generate it only where it is needed. This would allow using it in an existing page or component. One could also generate json file with the front matter contents and dynamically fetch them on the client. However that would cause empty pages to initially render. For our use case this would be acceptable, but still not ideal.

[muuki88]

Just wanna share what I tried. Thanks for the allContentLoaded callback 🎉 Super useful.

The plugin looks like this

import { LoadContext, PluginModule } from "@docusaurus/types";
import { DocFrontMatter, LoadedContent, LoadedVersion } from "@docusaurus/plugin-content-docs";
import fs from 'fs';
import path from 'path';

export interface TocPluginOptions {
    /** reference the docusaurus-content-docs plugin id */
    contentDocsId: string;

    /**
     * filter the relevant doc files to generate
     */
    filter: (doc: DocFrontMatter & Record<string, unknown>) => boolean;

    /** where to put the JSON file */
    output: string;
}


export const tocPlugin: PluginModule<TocPluginOptions> = (context: LoadContext, options: TocPluginOptions) => ({
    name: 'toc-plugin',
    allContentLoaded({ allContent, actions }) {
        if (!options.contentDocsId) {
            return Promise.reject('No contentDocsId provided');
        }

        // access the loaded content from the content-docs plugin
        const loadedContent = allContent['docusaurus-plugin-content-docs'][options.contentDocsId] as LoadedContent;

        // TODO: handle multiple versions properly
        const currentVersion = loadedContent.loadedVersions.find((version: LoadedVersion) => version.versionName === 'current');
        if (!currentVersion) {
            return Promise.reject('No current version found');
        }
        const filteredDocs = currentVersion.docs.filter(options.filter);

        const output = filteredDocs.map((doc) => ({
            source: doc.source,
            permalink: doc.permalink, // FIXME seems to be the same for different versions
            title: doc.title,
            meta: doc.frontMatter,
        }));

        const outputPath = path.resolve(context.siteDir, options.output);
        fs.writeFileSync(outputPath, JSON.stringify(output, null, 2), 'utf-8');

    },
});

and the configuration like this

    [tocPlugin, {
      filter: (doc) => doc.frontMatter.layout === 'feature-x',
      contentDocsId: 'product-a',
      output: 'docs/product-a/features.json'
    }],

The only thing I'm unsure about, is the permalink and how to do this with versions. When I release, the link is set to next, which is a bit unfortunate.