Skip to content
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

Merged
merged 12 commits into from
Jun 7, 2018
Merged

Conversation

endiliey
Copy link
Contributor

@endiliey endiliey commented May 26, 2018

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
3 correct_sidebar

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

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

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
6 deeper than 1 level still work

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

nodoc

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

subdir sidebar

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 :)
versioning wohooooooooo

Version 1.1.6 projectA/README
1 1 6 readme

Version 1.1.7 projectA/README
1 1 7 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
korean

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

Credits

@ryanwilsonperkin for helping me to testing it out previously

@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label May 26, 2018
@endiliey endiliey force-pushed the subdir branch 2 times, most recently from 06fe96e to e9dbe7b Compare May 26, 2018 17:19
@docusaurus-bot
Copy link
Contributor

docusaurus-bot commented May 26, 2018

Deploy preview for docusaurus-preview ready!

Built with commit 2a84d97

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

@endiliey endiliey changed the title [WIP] Enable subdirectory for docs [#323] Enable subdirectory for docs May 28, 2018
@endiliey endiliey changed the title [#323] Enable subdirectory for docs [#323] Enable sub-directories in docs/ May 28, 2018
@endiliey endiliey changed the title [#323] Enable sub-directories in docs/ [#323][WIP] Enable sub-directories in docs/ May 28, 2018
@endiliey endiliey changed the title [#323][WIP] Enable sub-directories in docs/ [#323] Enable sub-directories in docs/ May 28, 2018
@ryanwilsonperkin
Copy link

@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
Copy link
Contributor Author

endiliey commented May 30, 2018

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
Copy link

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

@ryanwilsonperkin
Copy link

ryanwilsonperkin commented May 30, 2018

@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
Copy link

ryanwilsonperkin commented May 30, 2018

@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
Copy link
Contributor Author

endiliey commented May 31, 2018

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

@endiliey endiliey changed the title [#323] Enable sub-directories in docs/ [WIP] [#323] Enable sub-directories in docs/ May 31, 2018
@endiliey endiliey force-pushed the subdir branch 5 times, most recently from b8b8f5b to a2318ec Compare May 31, 2018 09:15
@endiliey endiliey changed the title [WIP] [#323] Enable sub-directories in docs/ Enable sub-directories in docs/ May 31, 2018
@ryanwilsonperkin
Copy link

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

@endiliey endiliey changed the title Enable sub-directories in docs/ [WIP - Want to add more tests] Enable sub-directories in docs/ Jun 1, 2018
@endiliey endiliey changed the title [WIP - Want to add more tests] Enable sub-directories in docs/ [WIP] Enable sub-directories in docs/ Jun 1, 2018
@endiliey endiliey force-pushed the subdir branch 3 times, most recently from e1f085f to cac3ce4 Compare June 1, 2018 13:54
@endiliey endiliey changed the title [WIP] Enable sub-directories in docs/ [Need Help to Test] Enable sub-directories in docs/ Jun 1, 2018
@JoelMarcey
Copy link
Contributor

@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
Copy link
Contributor Author

endiliey commented Jun 7, 2018

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%'
Copy link
Contributor

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?

Copy link
Contributor

@JoelMarcey JoelMarcey left a 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!

@jsprklst
Copy link

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

@endiliey
Copy link
Contributor Author

@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
Copy link

@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
Copy link
Contributor Author

@jsprklst

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

@jsprklst
Copy link

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

@endiliey
Copy link
Contributor Author

@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
1

Works perfectly on the website
react

@richburdon
Copy link

Anyone still working on this?

@JoelMarcey
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants