search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
55.43k stars 8.31k forks source link

Customizable blog folder #359

Closed sudhirj closed 5 years ago

sudhirj commented 6 years ago

Is there any reason why docs are outside the website folder but blog posts are inside? And there's no customization allowed either?

Is it because projects at FB already tend to have a docs folder, but not necessarily a blog? If that's the case, it would be great to have it customizable, for cases where the website is being set up as a first class citizen in its own repo.

neilsutcliffe commented 6 years ago

At this time the blog folder is hard-coded. It would make sense to have it in the web-config like the docs does.

return siteConfig.customDocsPath ? siteConfig.customDocsPath : 'docs';

I believe this is as there are no markdown files inside the website folder. Everything inside the website folder is either a html template of a js React component.

This would be a small change to make as the default is sensible ATM, would just mean having to reference the variable in 3 to 4 places.

Time to implement is probably about an hour or two

JoelMarcey commented 6 years ago

@sudhirj @neilsutcliffe Hi! We made a conscious decision to only have docs outside of the website folder. We did this to try to maintain a semblance of simplicity and approachability for Docusaurus. Generally all websites will have documentation. Much less will have a blog, and we didn't want to confuse the issue by appearing that a blog was required, etc.

We could possibly have a config for this, yes -- technically it wouldn't be that difficult -- but I would want to make sure with my team here that we want to stray away from that design principle.

neilsutcliffe commented 6 years ago

We were so preoccupied with whether or not we could, we didn’t stop to think if we should. ~Jeff Goldblum (ish)

JoelMarcey commented 6 years ago

@neilsutcliffe Ha ha ha - nice quote 👍

JoelMarcey commented 6 years ago

Reminds me that I should watch the original Jurassic Park again.

sudhirj commented 6 years ago

Makes a ton of sense to do it this way when injecting Docusaurus into an existing project - so kudos for making that really well thought out and easy.

Docusaurus works great as a first class citizen as well, though, it would be a shame if the defaults look odd when initialized as a standalone project. Slash ought to be happy to be a strong independent saurus.

JoelMarcey commented 6 years ago

@sudhirj That's a fair point. Let me tag this as enhancement and look at seeing how we can make this happen so that is satisfies both our requirements. Thanks!

JoelMarcey commented 6 years ago

Yeah, we could probably do something similar like did with the docs folder where we allowed a customizable path.

pixie79 commented 5 years ago

bump - is there any update on this as it would be more ideal for us as different external parties work on docs and blogs. Then we can mount the two together for build.

Thanks

endiliey commented 5 years ago

This issue is closed due to

  1. Stale activity
  2. It won't be addressed in current version but has been addressed in the next major version