search

facebook / docusaurus

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

Docusaurus 2 #789

Closed yangshun closed 3 years ago

yangshun commented 6 years ago

Update 03/19/19

We have started a Roadmap/Feature requests page thanks to the awesome folks at Canny.io. Have a go at it on our WIP v2: https://v2.docusaurus.io/feedback/

These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators.

In the current JavaScript-based static site generators ecosystem, there are the following libraries:

Useful libraries

My proposal for D2 is that Docusaurus be responsible for documentation content, routing, translation and versioning, leaving layout and styling to the end user. Docusaurus would provide a default theme and a few common layouts that the user can use, or ignore if they want to build their layout from scratch. It's not a good idea for Docusaurus to maintain the entire layout and styling as these stuff are hard to make improvements without breaking existing users' code.

A Google Doc where we go into more details can be found here

D2 Design Principles

D1 Problems and Proposed Solutions

Infra

Current Problems

Suggested improvements

HTML/CSS

Current Problems

Suggested improvements

JavaScript

Current Problems

Possible improvements

API

Current Problems

Possible improvements

Blog

Current Problems

Possible improvements

Markdown

Current Problems

Possible improvements

Search

Current Problems

Possible improvements

These are my two cents. Feel free to chime in (:

ahmadalfy commented 6 years ago

+100 for moving the layout and styling outside Docusaurus' scope.

JoelMarcey commented 6 years ago

Thanks so much for staring the planning process here @yangshun. These are wonderful.

I will say a request for a local/offline search option should be considered for v2 as well -- we have had that request multiple times as well.

Also, I feel it is important to reiterate this -- no matter what features we add for v2, we always want to make sure we adhere to the overall mantra of Docusaurus which is "easy to create a documentation website", with the emphasis on "easy". It is always a tricky balance to add a bunch of features and keep things as simple as possible.

endiliey commented 6 years ago

This is exciting. webpack 🎉.

Extra things that I think will be great to have

Questions

yangshun commented 6 years ago

I will say a request for a local/offline search option should be considered for v2 as well -- we have had that request multiple times as well.

Added a section about search.

Also, I feel it is important to reiterate this -- no matter what features we add for v2, we always want to make sure we adhere to the overall mantra of Docusaurus which is "easy to create a documentation website", with the emphasis on "easy". It is always a tricky balance to add a bunch of features and keep things as simple as possible.

Yes! No worries we'll stick to this. It might just be troublesome for v1 users to migrate to v2 due to some potentially backward-incompatible changes we're making.

JoelMarcey commented 6 years ago

Whether we do this for 1.3+ or v2, we should also considering standardizing on one or both of the following:

caabernathy commented 6 years ago

Let's also think about integrating autogen systems into an upcoming version - see #78

JoelMarcey commented 6 years ago

Adding Docusaurus format support to hh-apidoc is not a Docusaurus v2 feature necessarily, but we can consider as something to help grow the use of it.

https://github.com/hhvm/hh-apidoc/issues/29

fredemmott commented 6 years ago

Ultimately I think it should be hh-apidoc's responsibility to provide documentation/metadata in a good format for docusuarus when wanted - but for user experience, it would be good if docusaurus were aware of it and would suggest/configure running it as part of the docusaurus build process rather than needing a separate predecessor step

prakhar-goel commented 6 years ago

+1 for offline search using lunrjs or similar. We are using Docusaurus for internal company documentation and therefore cannot use default Algolia search. Ability to search through markdown files would be a great add on to the current version.

kevinbarabash commented 6 years ago

It would be nice if https://github.com/facebook/Docusaurus/issues/852 could be addressed as part of v2.

chenglou commented 6 years ago

I really hope that Docusaurus can keep its initial simplicity; v2 sounds nice but there are several things I'm slightly worried about. By simplicity, I mean both the interface and implementation (I'll explain why I care about the latter, aside from being an occasional contributor/debugger myself, at the end). Docusaurus' rather solid, that and the crowdin support are the two reason why we switched away from other ultra ambitious generators with a complex webpack pipeline that failed to handle three digits number of markdown files...

Specifically:

Routing logic is separated and resides within both server and generation code, leading to duplicated logic and harder to ensure that code working in server mode also work in generation mode.

Yeah this is definitely a pain point we felt on the user side! I've noticed/filed/fixed a few of these.

Routing is not declarative. Hard to understand what possible routes there are in Docusaurus.

Not too sure what this means; isn't it glanceable in sidebars.json?

Current architecture is a bit tangled and makes it hard to introduce plugins.

Making it pluggable seems to always come with a tradeoff (relevant). I'm imagining that when I read the supposedly new siteConfig, I might see a list of clean but super opaque require calls instead of a js object config? This is what happened with other static generators. The complexity is hidden by all the third-party plugin requires but there's always some that behave weirdly and try to over-compose, like webpack configs.

LiveReload does a full-page reload, and page reloads for changes of all files

It's been quite fast from my experience; it's less of our business from the user side, but I'd love to see the Docusaurus codebase staying simple. It would be nice if siteConfig.js's changes are picked up though!

Use a module bundler like webpack

We switched to Docusaurus to avoid some of the more hardcore webpack and ecosystem problems. At the worst time, I was cherry-picking and deploying things manually each push. cc @rickyvetter who'd concur.

Actually, the watcher mode and the startup time has regressed quite a bit these days, but I didn't have the heart to point it out because Docusaurus has been serving us well 😅. It'd be nice to have it fast again... in fact, that's probably one of my biggest request. And I don't mean overengineer the pipeline to get a fast lazy startup; I mean the "good old days" where the startup was simple enough to stay within 1-2s. Webpack will blow past that budget.

Raw CSS without any preprocessor. Hacky variable substitution approach using regexp.

Most other CSS preprocessors aren't much of a step up from basically regexes lol. Given CSS' syntax, a single regex pass isn't actually that hacky; you might replace some words in comments but that's pretty much it. The one from Docusaurus has been blazing fast so far, so that's nice. But given that a preprocessor is opt-in, and given its limited scope, I think letting userland customize it sounds fine. Aka we don't pay the price for not using them, aside from maybe one or two checks in Docusaurus codebase.

Docusaurus controls much of the styles and layout, which makes it prone to breaking end users code who customize.

We're such folks, for all 3 sites. But I'd rather keeping up with the very occasional small layout breaking changes (very quick to check the css changes from changelog and fix them) than having them overly customizable (the point being that such customizability will probably affect Docusaurus' current setups).

All CSS is compiled into one file.

That has been very fine so far! Kinda like how non-nonsense it is.

HTML/CSS is self-written and doesn't follow CSS framework best practices. Typography is not great (margins and paddings are not consistent)

Yeah fixing those would be great!

No 404 page.

Oh yeah, a custom URL redirect json config would be sweet. We made our own for our sites by essentially putting dummy placeholder redirect pages.

Anyway, the gist is that, we really appreciated Docusaurus' non-nonsense toolchain, and whatever depth-related improvements (like even better page layout) are super welcome. Reaching too much for breath and becoming essentially another "website compiler" seems a bit much; after all, we do want to just focus on the documentation, and no matter how hard folks try to compiler-fy websites to regain the ease of use, simplicity and performance, we've not seen such effort that hasn't leaked hard into userland so far. Won't point fingers though. Also, sorry if some of the spirit I've summarized here wasn't part of Docusaurus' initial goal; we might happen to have piggy backed on top of it.

Thanks a lot for your continued work 😃

muuvmuuv commented 6 years ago

+1 for Gatsby.js. This would make Docusaurus so flexible and modular

sunnylqm commented 6 years ago

Can we have a roadmap for v2 like this? https://github.com/react-navigation/react-navigation/issues/4434 @yangshun

JoelMarcey commented 6 years ago

@chenglou Thank you so much for your thoughtful feedback. I am in 100% agreement with your overall premise that Docusaurus needs to be true to its original charter of "easy and simple" for open source websites. I believe the v2 leads, @endiliey and @yangshun, understand that and believe that too.

The v2 folder has been added to the repo so we can keep tabs on the progress of the implementation.

yangshun commented 5 years ago

A more detailed v2 document can be found here. Comments are welcome!

Would like to give interested parties a heads up that v2's progress is delayed due to manpower constraints on our end (no one full-time working on the project). We hope to have a beta ready by mid 2019, dogfood on Facebook's Docusaurus sites, and launch in Q4 2019.

JoelMarcey commented 5 years ago

That said, if anyone is interested in joining our effort as a direct contributor to v2 (or maintainer of v1), let us know. We would love the help.

ymschaap commented 5 years ago

@yangshun @JoelMarcey I've been following the project for a while now. Have 10+ year experience in front-end development, lots of React+webpack work and would be able to commit time to join the effort on getting 2.0 launched.

JoelMarcey commented 5 years ago

@yangshun, @endiliey -- what is the best way for @ymschaap and @henrystevens (who I chatted with offline) to get started helping with v2?

endiliey commented 5 years ago

This might need more discussion. But one of the useful thing that can be done for those who wanted to help with v2 is to actually test & play around with the on-going v2 implementation

There is an instruction on how to run it locally.

Edit: Alternatively, join us on discord

amimas commented 5 years ago

One of things I've noticed in the V1 is that when you have versioning enabled, each versioned docs require a original_id, which is supposed to correspond to another doc in the "next" release doc id.

I'm not sure why this is a hard requirement. Removing a doc from the next release seems to be a blocking issue if that doc exists in a versioned doc. I know the versioning mechanism is being looked into for V2. I hope this will be addressed in that.

endiliey commented 5 years ago

I'm not sure why this is a hard requirement. Removing a doc from the next release seems to be a blocking issue if that doc exists in a versioned doc

@animas great for noticing this. This is also somewhat a painful point that I've encountered. Hence why we're thinking we should not assume every "updated" version docs has an "original" docs in the previous version. We are indeed looking to re-work on the v2 versioning mechanism.

nebrelbug commented 5 years ago

If the user adds interactivity to their React component/page, we should include React library on the page and hydrate the component after the page has been rendered.

Please, yes! That's been one of my main frustrations with Docusaurus.

nebrelbug commented 5 years ago

What about offline support (probably by making the docs PWAs)? It would be relatively easy to set up, and it could be opt-in.

yangshun commented 5 years ago

We have started a Roadmap/Feature requests page thanks to the awesome folks at Canny.io. Have a go at it on our WIP v2: https://docusaurus-2.netlify.com/feedback/

Berkmann18 commented 5 years ago

+1 For emojis and for offline support.

emanic commented 5 years ago

Are there any plans to support variables and templating a la Liquid/Jekyll, go/Hugo? I did not see any mention of adding this in D2, but it would be extremely useful.

yangshun commented 5 years ago

Are there any plans to support variables and templating a la Liquid/Jekyll, go/Hugo? I did not see any mention of adding this in D2, but it would be extremely useful.

@emanic React is used as a templating library in D1, this is supported out of the box in D1 and will continue to be a thing in D2.

nebrelbug commented 5 years ago

@yangshun it would be very nice to allow customizing template engines as well.

yangshun commented 5 years ago

@nebrelbug That'll be a little hard because the whole framework will be built upon the React ecosystem as we use React Router, React Helmet. Docusaurus' direction isn't to be so customizable at such a low level. That said, you can still use React as a shell to render your static HTML that's rendered using another templating engine, but I can't think of good reasons to do that.

endiliey commented 5 years ago

About the template engines, I think that can be left as a plugin.

Possible example: let’s say we want to create a template that allows you to import code snippet from a file in markdown. That means we’re replacing all the “template syntax” string occurence in markdown with the actual code snippet. This can be done by overriding the webpack markdown-loader.

nebrelbug commented 5 years ago

@yangshun ah, that makes sense.

@endiliey good idea!

emanic commented 5 years ago

Are there any plans to support interactive SVGs, such as one that displays tooltips on mouse hover? I have found that none of the common methods of making the SVG interactive work in the Docusaurus site. For example, let's take the simplest method, using the <title> tag. I can add the <title> tag and I see the tooltip when I open the SVG outside of my Docusaurus website, but when I display the same SVG inside of the Docusaurus site, no joy. Of course, I would ultimately like to do something more sophisticated than just using the <title> tag.

Update: I have found that if I use <embed src="file.svg" type="image/svg+xml" />, the <title> tooltip shows up. This requires some HTML, but it seems to work.

ahmadawais commented 5 years ago

I'd appreciate the ability to have multiple links forwarded/redirected to the same document. Iterating on what @endiliey said:

---
title: Getting Started
Links: getting-started, start, go
---

Now with that, I could use short link like docs.mysite.com/go and that goes to docs.mysite.com/getting-started the first link. But also docs.mysite.com/start goes there.

blling commented 5 years ago

How to init a Docusaurus v2 project ?

endiliey commented 5 years ago

@lovoop currently we haven't implemented the init part of Docusaurus v2 yet because there are several areas still in progress (e.g: responsive styling, theming, plugins, etc) and we don't want people to actually install it yet/ even using it in production yet.

Edit: If you wanted to give a taste of docusaurus 2. Read this short unofficial blog post of mine https://endiliey.com/2019/05/16/docusaurus-2-technical-preview/

ericnakagawa commented 5 years ago

I'd appreciate the ability to have multiple links forwarded/redirected to the same document. Iterating on what @endiliey said:

---
title: Getting Started
Links: getting-started, start, go
---

Now with that, I could use short link like docs.mysite.com/go and that goes to docs.mysite.com/getting-started the first link. But also docs.mysite.com/start goes there.

This would affect how sitemaps are generated, also relates to 301 redirects.

Would the first item in the list be the canonical example that the others are redirected to or should we be generate multiple redundant files?

afrankel-sfdo commented 5 years ago

didn't see this on the list: per language assets. useful when images contain information that needs to be translated.

emanic commented 5 years ago

Perhaps I can explain more specifically what I am looking to do and you can see if this is something you may want to add to v2, but more importantly I would appreciate some guidance on how I might accomplish it with v1. We have versioned docs and need to display different content to users based on which version of the docs they are looking at. We want to be able to identify what should be replaced in the markdown using something like this {{variable}}. In the immediate term, we need this for download paths inside of code blocks so that they can copy and paste code that gets them the correct client for their version. Longer term, we want to show different chunks of texts and even different navigation based on the version. I saw the discussion here https://github.com/facebook/Docusaurus/issues/395, unfortunately, this does not satisfy my use case. I understand that some of this would be in a remarkable plugin (though none exist at present that we can use), but also, we need to be able to set the strings, navigation, content chunks via React. Any tips would be appreciated.

CGick commented 5 years ago

I am migrating my companies product documentation to Docusaurus, and a lot of our pages are referenced by other pages. It would be nice to have a reference mapping file in which I can add all of the link ids and the link address they map to, then in my docs pages just enter the link id and have it pull the link address from the mapping file. If this is currently possible could someone please let me know how this is done.

joetidee commented 5 years ago

Is there a rough timeline for the beta and full releases of v2?

Berkmann18 commented 5 years ago

Is there any estimated release time or something?

iamandrewluca commented 5 years ago

Proposal: Evergreen documentation

I don't think this should be implemented into Docusaurus, but to keep in mind.

From times to times it happens that docs remain behind code. Would be great to have a validator that will test if docs reflect latest code changes. I think it could be used as a prebuild step.

This package allows to validate documentation files https://github.com/Originate/text-runner

Are there other alternatives?

endiliey commented 5 years ago

Is there a rough timeline for the beta and full releases of v2? Is there any estimated release time or something?

There is no rough estimated timeline, but I guess we're pretty close to beta at least.

If you want to see it shipped faster, try it today https://v2.docusaurus.io/ and give feedback. You can also contribute by sending pull request, sponsoring us on Open Collective and/or chat with us on Discord. We need help 😉

We don't want to release unready version, that's why we opt-ed to stay in alpha as much as we can to ensure its stable and we "do it right". Actualy, many are using alpha versions for production. It has matured, docsearch is using it, CRA is using it and actually we're planning to migrate Redux's site soon to use the alpha version. Breaking changes has been very easy so far, as long as you know basic React and JavaScript.

Some people are adventurous enough as well with the customization. Example:

https://vector.dev/ image

https://uniforms.tools/ image

Berkmann18 commented 4 years ago

What's the timeframe for v2 coming out?

JoelMarcey commented 4 years ago

@Berkmann18 Hi. As you may or may not know, a generally stable alpha of v2 is out now - https://v2.docusaurus.io. Sites, including those from Facebook Open Source, are using it. The reason it is not "fully released" yet is that it is missing a key piece of functionality that is currently in v1 -- localization support. That is being worked on now. If you don't need that, then you might find that v2 already serves your needs.

To answer your question though - v2 replacing v1 (i.e., v1 is deprecated) hopefully sometime in the next couple of months.

cc @yangshun @slorber

Berkmann18 commented 4 years ago

@JoelMarcey In that case, I guess I'll wait then as the project where we use Docusaurus relies on translations provided via Crowdin.

honi commented 4 years ago

Is there any documentation regarding Infima theming variables or an ETA for Infima source code release?

slorber commented 4 years ago

@honi apart the website and inspecting, source is not yet available. FB policy is not really to publish projects that are not ready. But Infima is probably not very far. We'll see how to make this available soon.

uditalias commented 4 years ago

I created this simple CSS gist that shows how you can add Line Numbers to code blocks.

https://gist.github.com/uditalias/3969a20ef759bf3a8757499429b30063

You can see it in action here: https://www.injex.dev/docs/api/core/decorators/inject

thibaudcolas commented 3 years ago

Following from https://github.com/facebook/docusaurus/issues/789#issuecomment-634721378, are there good issues to subscribe to for people who are waiting on localization support? I see #3524 for the Jest website, which has big localization requirements I assume. Are there any others?

I’m considering Docusaurus for a big documentation site, localization support is a hard requirement, it’s unclear how far ahead Docusaurus v2 is with this in particular.