Add Markdoc to the doc tools

[ericholscher]

This highlights the test-builds repo,
and contains the basic config to make it build on RTD.

This doesn't address any integration info,
but I wanted to get a basic page up to start getting SEO.

---

📚 Documentation previews 📚

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

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

[humitos]

I'm happy you did this work!

I noticed there are a few files that break in when loading https://test-builds.readthedocs.io/en/markdoc/ when checking the console.

It seems there are some URLs that add an extra /doc/ in the path that shouldn't be there. Example:

• Go to https://test-builds.readthedocs.io/en/markdoc/docs/
• The site tries to load https://test-builds.readthedocs.io/en/markdoc/docs/_next/static/chunks/605040ef-a8879c674f60e9a8.js
• The correct file is https://test-builds.readthedocs.io/en/markdoc/_next/static/chunks/605040ef-a8879c674f60e9a8.js

[humitos]

We should also add a limitation section here since I understand that there are no HTML files generated for each page, similar to Docusaurus: #11752 (review)

[ericholscher]

HTML files are generated:

-> find out |grep html
out/index.html
out/404.html
out/docs/index.html
out/404/index.html

[humitos]

Hrm, interesting. In the tutorial/documentation page that I read about the HTML generator I'm sure it said that it was a SPA and the content was rendered on the fly, 🤷🏼

[ericholscher]

Search works:

[humitos]

It seems there are some URLs that add an extra /doc/ in the path that shouldn't be there. Example:

I think it's because we are using assetPrefix together with basePath. I understand we only need basePath here: https://nextjs.org/docs/pages/api-reference/next-config-js/assetPrefix

[ericholscher]

Yep, I just pushed up a fix.

[humitos]

I don't really understand why it doesn't work reliably. If I go to the home and click on "Overview" it loads correctly. However, if I go directly to the overview page (https://test-builds.readthedocs.io/en/markdoc/docs/) it doesn't 🤷🏼

[ericholscher]

The build was broken, so it wasn't picking it up.

[ericholscher]

The build was broken, so it wasn't picking it up.

[humitos]

The build was broken, so it wasn't picking it up.

Cool, it works perfect now 🚀