Enable sub-directories in docs/

[endiliey]

Motivation

Resolves #323

Have you read the Contributing Guidelines on pull requests?

Yes

Want to test live example ?

1. Website with translation + subdirectories
   https://endiliey.com/docs/ko/docusaurus/introduction.html
   https://endiliey.com/docs/id-ID/projectA/readme.html
   https://endiliey.com/docs/zh-CN/projectA/docs/contributors.html

2. Website with versioning + subdirectories
   https://docusaurus-airutgnkay.now.sh/docs/en/next/projectA/docs/architecture.html
   https://docusaurus-airutgnkay.now.sh/docs/en/1.1.6/docusaurus/about.html
   https://docusaurus-airutgnkay.now.sh/docs/en/docusaurus/about.html

Test Plan

1. Prepare test docs
Note that we are mixing flat & subdirectory docs hierarchy. This is to prove that this PR is backward compatible & still allow flat docs hierarchy in addition of sub-directories hierarchy

// ......
├── api-commands.md
├── api-doc-markdown.md
├── api-pages.md
├── api-site-config.md
├── projectA
│   ├── docs
│   │   ├── architecture.md
│   │   └── contributors.md
│   └── README.md
└── projectB
    └── guides
        └── install.md

4 directories, 19 files

2. Modify sidebars.json

{
    // ........
    "API": [
      "commands",
      "doc-markdown",
      "api-pages",
      "site-config"
    ],
    "Project A": [
      "projectA/readme",
      "projectA/docs/architecture",
      "projectA/docs/contributors"
    ],
    "Project B": [
      "projectB/guides/install"
    ]
  }
}

3. Test development

cd website
yarn start

Check that sidebar is correct
http://localhost:3000/docs/en/next/installation.html

Check that docs in subdirectory can be accessed
http://localhost:3000/docs/en/next/projectA/readme.html

Check that next and previous button is working
http://localhost:3000/docs/en/next/projectA/readme.html

Check that docs in subdirectory of subdirectory can be accessed (not just one level deep)
http://localhost:3000/docs/en/next/projectA/docs/contributors.html

4. Test production build with python SimpleHttpServer

cd website
yarn build
cd build/Docusaurus
python -m SimpleHTTPServer 8000

1. Doc still works & sidebar is correct
   http://localhost:8000/docs/en/next/custom-pages.html

2. Subdir docs is working & sidebar is correct
   http://localhost:8000/docs/en/next/projectA/docs/contributors.html

5. Check generated build files

cd website
yarn build
tree -a -I "css|CNAME|.circleci|img|js" build/Docusaurus/docs/ > build.txt

Results are expected
Full generated files structure can be seen at https://gist.github.com/endiliey/a8492aee8e761d079a779f5010219bad

Notice that .html files are built for docs in subdirectory

build/Docusaurus/docs/
├── en
│   ├── api-pages.html
│   ├── blog.html
│   ├── commands.html
│   ├── custom-pages.html
│   ├── doc-markdown.html
│   ├── installation.html
│   ├── navigation.html
│   ├── next
│   │   ├── api-pages.html
│   │   ├── blog.html
│   │   ├── commands.html
│   │   ├── custom-pages.html
│   │   ├── doc-markdown.html
│   │   ├── installation.html
│   │   ├── navigation.html
│   │   ├── projectA
│   │   │   ├── docs
│   │   │   │   ├── architecture.html
│   │   │   │   └── contributors.html
│   │   │   └── readme.html
│   │   ├── projectB
│   │   │   └── guides
│   │   │       └── install.html
│   │   ├── publishing.html
│   │   ├── search.html
│   │   ├── site-config.html
│   │   ├── site-creation.html
│   │   ├── site-preparation.html
│   │   ├── translation.html
│   │   └── versioning.html
│   ├── publishing.html
│   ├── search.html
│   ├── site-config.html
│   ├── site-creation.html
│   ├── site-preparation.html
│   ├── translation.html
│   └── versioning.html
├── installation.html
├── navigation.html
├── next
│   ├── api-pages.html
│   ├── blog.html
│   ├── commands.html
│   ├── custom-pages.html
│   ├── doc-markdown.html
│   ├── installation.html
│   ├── navigation.html
│   ├── projectA
│   │   ├── docs
│   │   │   ├── architecture.html
│   │   │   └── contributors.html
│   │   └── readme.html
│   ├── projectB
│   │   └── guides
│   │       └── install.html
│   ├── publishing.html
│   ├── search.html
│   ├── site-config.html
│   ├── site-creation.html
│   ├── site-preparation.html
│   ├── translation.html
│   └── versioning.html

6. Versioned docs test !!

cd website
yarn run version 1.1.6

Make some changes on projectA/readme.md

yarn run version 1.1.7

Look at generated versioned_docs. It works :)

Version 1.1.6 projectA/README

Version 1.1.7 projectA/README

7. Translation test
As docusaurus main website does not have a translation ready, I used my own site to test this feature.

My doc structures:

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

5 directories, 6 files

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

https://endiliey.com/docs/zh-CN/projectA/readme.html

Credits

@ryanwilsonperkin for helping me to testing it out previously

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit 2a84d97

https://deploy-preview-705--docusaurus-preview.netlify.com

[ryanwilsonperkin]

@endiliey thanks for working on this! This feature would be super useful for us, we're using Docusaurus to aggregate several repositories into a central set of docs. Right now we've just written a bit of a hack to make it work, so if you need any help with this PR I'd be happy to pitch in.

[endiliey]

Thank you @ryanwilsonperkin

Actually you can help by testing it & letting us know your opinion on what is the right / better behavior should be like.

About this PR:

1. User can now optionally write their docs in a subdirectory of docs/ folder. Example: docs/guides/announcement.md and that doc will be available on {siteUrl}/docs/en/guides/announcement.html (assuming language is set to english)
2. User can still store docs on a flat way. Example docs/test.md and that doc will be available on {siteUrl}/docs/en/test.html

[ryanwilsonperkin]

@endiliey I'll be trying out this branch today with our project and reporting back with results in a couple of hours 👍

[ryanwilsonperkin]

@endiliey I've been playing around for this a bit this afternoon and noticed what might be an issue, or might be deliberate. It seems that this PR only takes us 1 directory deeper, and not recursively into any number of nested directories. Is that correct?

For example, if I have the following layout:

repo/
    docs/
        overview.md
        projectA/
            README.md

then I get the URLS:

/docs/overview.html
/docs/projectA/README.html

However, if I have the following layout:

repo/
    docs/
        overview.md
        projectA/
            README.md
            docs/
                architecture.md

I don't get a /docs/projectA/docs/architecture.html as I would have expected.

Can you comment on whether or not you think this should be supported with this branch?

[ryanwilsonperkin]

@endiliey I've found a solution that would allow additional nesting of directories, by modifying your change from:

const curDir = path.dirname(file.split(getDocsPath() + '/')[1]);

to:

const relativeFile = path.relative(
  path.join(CWD, '../', getDocsPath()),
  file
);
const curDir = path.dirname(relativeFile);

This allows my use case of nested directories to work without any other changes being required to the PR.

I've pushed a branch matching yours to my own fork if you'd like to compare: https://github.com/ryanwilsonperkin/Docusaurus/tree/subdir

[endiliey]

Thank you @ryanwilsonperkin. that is correct & intended. My definition of subdirectory is just for one level deeper, but I can make the changes if you think we should support it recursively deeper.

Your solution will work but lack the changes for the 'next' and 'previous' button linking in Docslayout.js
Let's say we have this hierarchy

docs/
    a/
       b/
          x/
            test.md
    c/
        another.md

And put that on sidebars.json, the link still build the relative path only one level deep.
Because of my code

if (prevDir !== curDir && curDir != '.') {
  prevLink = '../' + prevLink;

I will make the changes, properly test it with many deep variations of subdirectory today when i got to reach my pc

Edit: PR Updated.
This should work now regardless of how deep is the docs (subdirectory of subdirectory also works).

Todo:
Remove the test docs & newly added sidebars after it is approved

[ryanwilsonperkin]

Awesome, thanks @endiliey! Things seem to be working great now

[JoelMarcey]

@endiliey 👍 ❤️

We are ready to merge this 😄

I just wanted to know if your fix to the translated sidebar problem should still be included in here? Or if we should just use #709 for it? Or are they solving two different things?

[endiliey]

We should use this because #709 won't be able to solve multilingual bug for subdirectory. It could misclassify subdirectory as language

[JoelMarcey]

Should the Crowdin example shown at https://docusaurus.io/docs/en/translation#crowdin be updated with this change?

[JoelMarcey]

Here we go. Another one of our more requested features!

[jsprklst]

Is it also possible to put images in an 'assets' folder in the subdirectory?

[endiliey]

@jsprklst
unfortunately no. I think it's confusing to put it in docs/your-subdir/assets. However, it can be placed in docs/assets/your-subdir (example: docs/assets/your-subdir/blabla.png) or you can put it in website/static/.

[jsprklst]

@endiliey thanks for your reply. I already tried your suggestion but the problem there is that the images won't display when previewing markdown files. Referencing images using ../assets/subdir/blabla.png breaks when using translations as it will resolve to docs/en/assets/subdir/blabla.png instead of docs/assets/subdir/blabla.png. Any suggestions?

[endiliey]

@jsprklst

https://docusaurus.io/docs/en/doc-markdown#linking-to-images-and-other-assets
![alt-text](assets/subdir/blabla.png.png)

[jsprklst]

@endiliey but then the image won't display when previewing markdown files in a subdir. Or am I missing something?

[endiliey]

@jsprklst

Well, isn't what matter is that it works on the website itself ?
You can look at react-native-docs, the preview on markdown files also doesn't work
https://github.com/facebook/react-native-website/blob/master/docs/alert.md

Works perfectly on the website

[richburdon]

Anyone still working on this?

[JoelMarcey]

@richburdon - when you say "this", what are you referring to? Some of this was merged.