Is it possible to ignore the last level of folder when using autogenerated sidebars?

[Ouch1978]

Hi,

I do like the new feature supporting sub folder about blog.

I'm wondering if it is possible to have the last level folder ignored when I'm using the autogenerated sidebars feature?

Let say, I have the folder structure:

docs
|-- category1
    |-- document1
        |-- document1.md
        |-- image01.png
        |-- image02.png

I would like to put markdown file and related assets in the same folder to get better edit experience and also management.

And the autogenerated sidebar will be:

docs
|-- category1
    |-- document1 (generated by folder)
        |-- document1 (generated by md file)

Is it possible to ignore the generated by folder one while using autogenerated sidebars?

Thank you.

[slorber]

Hey

Currently, it is not possible but it makes sense to me.

I guess it does not make much sense for a category to have only a single doc in it.
So it probably makes sense in such a case to not create a category by default (unless there's a category config file).

[Ouch1978]

Is it possible to add this feature in future version?

Since there are some non-tech guys editing markdowns direct with WebIDE, it take additional efforts to make it able to be preview if the related assets are stored in other folders.

Even we don't create a category folder, we still need to create folders for each document, and the problem still exist.

docs
    |-- document1 (generated by folder)
        |-- document1 (generated by md file)
    |-- document2 (generated by folder)
        |-- document2 (generated by md file)

We do use the category configuration file, but seems it cannot solve this problem.

For ex:

docs
    |-- document1
        |-- _category_.json
        |-- document1.md
        |-- image01.png
        |-- image02.png
    |-- document2
        |-- _category_.json
        |-- document2.md
        |-- image01.png
        |-- image02.png
generates

docs
    |-- Category1
        |-- document1 (generated by md file)
    |-- Category1
        |-- document2 (generated by md file)

Document 1 and 2 are in the same category, but there will be a duplicated Category1 appear in sidebar.

[Siemienik]

The same effect will be riched by:

docs
    |-- _category_.json
    |-- document1.md
    |-- document1
        |-- image01.png
        |-- image02.png
    |-- document2.md
    |-- document2
        |-- image01.png
        |-- image02.png

[Ouch1978]

@saintmalik

Thank you for your suggestion.

In my opinion, it might be a workaround, but it will also bring another side effect on editing user experience.

Since the folders will be listed on the top and files will be listed below in most of the IDE tools.

Once the documents grow by time, it could be harder to find the folder related to the markdown file in file explorer or the file listing on web IDEs.

I think it will be better if we could put both markdown file and related assets in the same folder.
The link to the assets will also be much clear.

[Josh-Cena]

There's a workaround for current version:

You can configure sidebarItemsGenerator (https://docusaurus.io/docs/sidebar#customize-the-sidebar-items-generator) with something like:

function unwrapCategory(items) {
  return items.map((item) => {
    if (item.type === 'category' && item.items.length === 1) {
      return item.items[0];
    }
    return item;
  });
}

sidebarItemsGenerator: async function ({defaultSidebarItemsGenerator, ...args}) {
  const sidebarItems = await defaultSidebarItemsGenerator(args);
  return unwrapCategory(sidebarItems);
},

FYI, using a _category_.json file under a folder is an explicit indication that this folder should be turned into a category, but here you want this folder to be a doc.

@slorber Maybe port #5309 to docs as well?

[Ouch1978]

@Josh-Cena

Actually, we seldom have just one document under a category.

However, I will revert to you later once I have it tested.

Thank you.

[Josh-Cena]

Okay, if you just want to unwrap the last level of folder, it's still possible:

function unwrapCategory(items) {
  return items.flatMap((item) => {
    if (item.type === 'category' && item.items.every((subitem) => subitem.type !== 'category')) {
      return item.items;
    }
    return item;
  });
}

Hope it helps

[Ouch1978]

@Josh-Cena

Thank you.

I'll have a try with this one and revert to you later.

[Ouch1978]

Hi @Josh-Cena

I've tried to customize the SidebarItemsGenerator, but I got error message and could not figure out how to solve it.

I modified docusaurus.config.js with:

  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
//        id: 'test',
        sidebarItemsGenerator: async function ({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
        }) {
          // Example: return an hardcoded list of static sidebar items
          return [{
              type: 'doc',
              id: 'doc1'
            },
            {
              type: 'doc',
              id: 'doc2'
            },
          ];
        },
      },
    ],
  ],

And got the error: Plugin "docusaurus-plugin-content-docs" is used 2 times with id default.

Then I unmarked the id line, then it said TypeError [ERR_INVALID_ARG_TYPE]: The "to" argument must be of type string.

Is it possible to provide me any clue or a working docusaurus.config.js example about sidebar customization?

Thank you.

[Josh-Cena]

Hey, you can refer to this doc section: https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#ex-config

You can pass the option through the preset instead of the plugin

[Ouch1978]

Hi @slorber ,

Seems the problem could also be solved by the new feature Category index convention in beta 10.

But I could not figure it out to make the category item show up in sidebar.
According to the document, it should be equivalent to using a category with a doc link.

Let say, I have the following folder structure:

docs
|-- guides
|-- guides.md

No matter I named the markdown file with the same of the folder, index.md or readme.md.
The link will not show up, but I could access it through typing the URL http://localhost/docs/guides.

May I have your assist please?

Thank you.

[Josh-Cena]

@Ouch1978 Is the guides category auto-generated?

[Ouch1978]

Hi @Josh-Cena,

No, It's not.

Sorry for I put the incorrect reference link, it should be https://docusaurus.io/docs/sidebar#category-index-convention.

Do I miss something else?

[Josh-Cena]

The conventions are only applied when: (1) the category is autogenerated and (2) no link has been explicitly given in _category_.json.

[Ouch1978]

Thank you.

I'll have another try.

[slorber]

Hey,

I'm not sure to understand what you tried exactly, and what's your exact setup, but yes this convention only applies for auto-generated sidebar slices, not sidebar items explicitly defined.

Now you posted:

docs
|-- guides
|-- guides.md

This is not exactly what the convention suggest, instead you should try:

docs
|-- guides
      |-- guides.md

ie using a filename like docs/guides/guides.md or docs/guides/index.md, not just docs/guides.md

This would lead to the equivalent sidebar:

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'guides',
      link: {type: 'doc', id: 'guides/guides'},
      items: [],
    },
  ],
};

Now, it may still not be the thing that you want, as your guide remains a sidebar category (has an arrow icon), not a simple doc sidebar item.

It could make sense that a folder that contains only a category index should be automatically be converted to a sidebar item instead of a category index, but it is not implemented atm. If we implement this, the sidebar could now look like this:

module.exports = {
  docs: [
    'guides/guides'
  ],
};

[hatton]

I needed something similar, which is to have what I'm calling "transparent" folders that don't generate a category. Here's what I ended up with:

module.exports = async function ({ defaultSidebarItemsGenerator, ...args }) {
  const sidebarItems = await defaultSidebarItemsGenerator(args);

  return hideTransparentFolders(sidebarItems);
};

// In order to keep images nearby to markdown and not lose links to them if we rename things, we
// can wrap each file in a folder that contains the MD and the images. However, sometimes this
// is not a natural category, so we wan that folder to be "transparent".  Our convention is to
// indicate that we want the folder to be transparent by appending "-" to the folder.
function hideTransparentFolders(items) {
  if (!items) {
    return items;
  }
  return items.flatMap((item) => {
    if (
      item.type === "category" &&
      item.label.indexOf("-") === item.label.length - 1 // name ends in our transparent folder indicator
    ) {
      return item.items;
    }
    if (item.items) {
      return {
        ...item,
        items: hideTransparentFolders(item.items),
      };
    } else {
      return item;
    }
  });
}