-
-
Notifications
You must be signed in to change notification settings - Fork 8.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Enable sub-directories in docs/ #705
Conversation
06fe96e
to
e9dbe7b
Compare
Deploy preview for docusaurus-preview ready! Built with commit 2a84d97 |
@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. |
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:
|
@endiliey I'll be trying out this branch today with our project and reporting back with results in a couple of hours 👍 |
@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:
then I get the URLS:
However, if I have the following layout:
I don't get a Can you comment on whether or not you think this should be supported with this branch? |
@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 |
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
And put that on sidebars.json, the link still build the relative path only one level deep. 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. Todo: |
b8b8f5b
to
a2318ec
Compare
Awesome, thanks @endiliey! Things seem to be working great now |
e1f085f
to
cac3ce4
Compare
We should use this because #709 won't be able to solve multilingual bug for subdirectory. It could misclassify subdirectory as language |
source: '/docs/*.md' | ||
translation: '/website/translated_docs/%locale%/%original_file_name%' | ||
source: '/docs/**/*.md' | ||
translation: '/website/translated_docs/%locale%/**/%original_file_name%' |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should the Crowdin example shown at https://docusaurus.io/docs/en/translation#crowdin be updated with this change?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here we go. Another one of our more requested features!
Is it also possible to put images in an 'assets' folder in the subdirectory? |
@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 |
https://docusaurus.io/docs/en/doc-markdown#linking-to-images-and-other-assets |
@endiliey but then the image won't display when previewing markdown files in a subdir. Or am I missing something? |
Well, isn't what matter is that it works on the website itself ? |
Anyone still working on this? |
@richburdon - when you say "this", what are you referring to? Some of this was merged. |
Motivation
Resolves #323
Have you read the Contributing Guidelines on pull requests?
Yes
Want to test live example ?
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
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
2. Modify sidebars.json
3. Test development
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
http://localhost:8000/docs/en/next/custom-pages.html
http://localhost:8000/docs/en/next/projectA/docs/contributors.html
5. Check generated build files
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 subdirectory6. Versioned docs test !!
Make some changes on
projectA/readme.md
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:
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