Support sub-directories in docs/

[steveklabnik]

I believe this is a feature request. If not, it's a request for docs 😄

I believe that currently, all docs files must live in the root of docs. I'd like to be able to group them together with subfolders.

Currently, it seems that directories inside of docs are simply ignored.

[hramos]

Right now Docusaurus expects all files to be on a flat docs/ folder. I believe this is a decision made to simplify internationalization support where docs/ would contain multiple sub-directories (one per language).

We can leave this open as a feature request in case someone wants to take a stab at implementing this.

[JoelMarcey]

@steveklabnik Hi! What @hramos says is basically correct. But, I wanted to correct one thing in your initial issue comment and his response:

I believe that currently, all docs files must live in the root of docs.
Right now Docusaurus expects all files to be on a flat docs/ folder

We implemented that you can put the docs in any directory you want. But the files have to be flat still.

See customDocsPath here: https://docusaurus.io/docs/en/site-config.html#optional-fields

[steveklabnik]

Gotcha! Thanks for the quick response :)

To be honest, I'm more concerned about the urls than I am about the directory structure. I'm experimenting with some API docs, and /api/foo/bar/baz.html is much nicer than api-foo-bar-baz.html. If there was a way to do this, while still keeping the flat structure, I'd be okay with that as well.

[JoelMarcey]

@steveklabnik We have a feature request (probably should be one of our top ones) to support custom permalinks. #101

That would help you sorta solve that problem too, right, assuming we don't get to non-flat doc structures first?

[steveklabnik]

I think so! Will comment over there too 👍

[viktorsmari]

I would also very much like to see the non-flat folder structure, allowing subfolders for better organization.
I have a large markdown codebase with subfolders I would like to migrate to Docusaurus. All the files are called index.md but live in their own folder. (It was migrated with Jekyll Wordpress exporter)
I also have non technical people editing the files on Github and they know how basic folder structure works and maps to real urls.

[kirtan403]

I think when markdown base increases, It would be hard to maintain it in a flat file structure. Just allowing sub-directories would be a very nice feature really. I am migrating to Docusaurus from gitbook and I think it will make it easy to maintain..

[pharophy]

I would also like to see subfolder support!

[endiliey]

Hello everyone who wanted sub-directories support in Docusaurus. I have submitted PR #705 for it, please help me to test it if you want to see it shipped faster😂.

I've personally tested this subdirectories in docs/ directly on my test site.

Example:

docs/
├── docusaurus
│   ├── about.md
│   └── introduction.md
├── projectA
│   ├── docs
│   │   ├── architecture.md
│   │   └── contributors.md
│   └── README.md
└── projectB
    └── guides
        └── install.md

https://endiliey.com/docs/ko/docusaurus/introduction.html

[JoelMarcey]

Hi @endiliey - You may have answered part of this in #709 (comment), but our concern re: this change was always around how it would affect translations and versioning. You think translations still work well - that's great! Have you test with versioning too?

[endiliey]

@JoelMarcey

Yes i have tested site with

1. Just versioning
2. Versioning & translation
3. Just translation

Edit: even Windows compatibility 😁
Edit 2: having real user to test it will be preferable

[zack9433]

Hi @endiliey

I think versioning is broken on v1.3.2 when I run yarn run version 1.0.0 and create versioned_docs versioned_sidebars, versions.json correctly. After created version, I run yarn start and shows some error message

Error: Processing the following `doc` field in `headerLinks` within `siteConfig.js`: 'edge/intro'. Check the spelling of your `doc` field. If that seems sane, and a document in your docs folder exists with that `id` value,
then this is likely a bug in Docusaurus. Docusaurus thinks one or both of translations (currently set to: false) or versioning (currently set to: true) is enabled when maybe they should not be.
Thus my internal id for this doc is: 'version-1.0.0-edge/intro'. Please file an issue for this possible bug on GitHub.

[endiliey]

@zack9433 mind giving a reproducible repo?

File a new bug issue if possible with repo 😊

[zack9433]

@endiliey seems like it's my settings problem and versioning is good right now. thx

[ishanmihir19]

@zack9433 Can you point which settings you changed to fix this issue. I seem to have run into the same issue.

Error: Processing the following doc field in headerLinks within siteConfig.js: 'designer-guide/introduction'. Check the spelling of your doc field. If that seems sane, and a document in your docs folder exists with that id value,
then this is likely a bug in Docusaurus. Docusaurus thinks one or both of translations (currently set to: false) or versioning (currently set to: true) is enabled when maybe they should not be.
Thus my internal id for this doc is: 'version-1.4-designer-guide/introduction'. Please file an issue for this possible bug on GitHub.

[danon]

If I have a directory structure like this

docs/
├── application
│   ├── about.md
│   └── introduction.md

Then in my sidebars.json, I need to put links like so:

{
  "docs": {
    "Application": [
      "application/about",
      "application/introduction"
    ],

which is fine for me.

My question is, what should ids of those about.md and introduction.md be? Can they be duplicated, each within different subdirectory? For example Feature1/about and Feature2/about?

[endiliey]

@danon yup. Because internally at Docusaurus their id will be Feature1/about and Feature2/about. So the id is namespaced.

Feel free to ping us on discord instead since GH issue reply might not be as fast

[danon]

What's your discord?

[yangshun]

@danon https://discordapp.com/invite/docusaurus

[amimas]

Does this only support one level of sub-directory under /docs? Can I have a directory structure like /docs/projectA/category1? If yes, what should the configuration be in sidebars.json? It seems I cannot add multiple layers in the sidebar

[robbiet480]

@zack9433 So I and other users are having this issue but you didn't provide a fix. Can you tell us what you had to change to get this working again so everyone benefits? Thanks!

[robbiet480]

Fix can be found at #1395 for those experiencing this in the future.