Docusaurus basics

[plaindocs]

Not a lot of info here, but probably worth pushing out anyway

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--11752.org.readthedocs.build/en/11752/

• Developer's documentation (dev): https://dev--11752.org.readthedocs.build/en/11752/

[stsewd]

From what I understand, docosaurus renders the docs with JS, that has the downside of some of our integrations that work over the generated HTML not working, like search and content embedding. Maybe have a limitations section?

[plaindocs]

@stsewd yup, sounds good, thanks

[humitos]

like search and content embedding

File Tree Diff won't work here either...

[humitos]

Looks good. As Santos mentioned, we should add a "Limitations" section before merging.

[humitos]

Once we merge and deploy #11710 this would be as following:

build:
  install:
    - cd docs/ && npm install
  build:
    html:
      - cd docs/ && npm run build
  post_build:
    - mkdir --parents $READTHEDOCS_OUTPUT/html/
    - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/

[ericholscher]

I'm 👍 on merging this now, so we can start getting some SEO from it.

[humitos]

I'm on the fence about the "Supported features" section. I'd probably remove it.

However, if we want to communicate what things don't work, I would probably re-phrase it as "Limitations" instead and only mention the things that don't work. That way, we don't need to repeat this list in all the pages of the documentation tools, and it's clearer what it doesn't work.

I think we should point all users to the addons index page for all the common features and each "Limitation" section should list only those that don't work.

My $0.02

[humitos]

By the way, in particular the example from Markdoc "Supported features" doesn't add too much value IMO and just adds confusions, since all the addons are listed there: https://github.com/readthedocs/readthedocs.org/pull/11782/files#diff-cb2fa2b006a3f660a46f7668df27803630c69192df00ca6f2da29bfb4f14464fR62

However, it doesn't mentioning redirects, environment variables, automation rules and a bunch of other features we do support for all the doctools. That's why I'm saying I'd prefer to remove the section and/or re-phrase it as "Limitations" instead. I think it will be clearer that only a subset of features are not supported.

[plaindocs]

I think a step back and a moment to consider the Supported Features is useful here. Are we sure it's clear to readers whether we're talking about RTD Features or Docusaurus Features?

We definitely don't want to add all of those to the Addons index, it'll get real busy, especially when we start adding more entries. So in general I'm in agreement with @humitos comments above.

But I also think we can merge and iterate.

[ericholscher]

I do think we want to highlight the features that work as a good way of marketing. If the goal of these pages is SEO, then people landing on it won't know about our platform features, so highlighting them is good. I do agree though that we probably want to frame this in a bit of a different way, and perhaps the website pages are where we're doing some of that work. So I've gone ahead and renamed it to limitations for now.