Allow building with custom docs

[JavierSegoviaCordoba]

Even Dokka (Kotlin documentation engine) is able to generate markdown files, I wouldn't want to deal with getting them looking good in Docusaurus. Instead, I would like to place the generated website (a bunch of HTML files and folders) inside docs in Docusaurus.

Is it possible to do that? I want to be able to redirect the user to the docs, but at the same time, I would like to get the advantage of getting versioned docs from Docusaurus.

[slorber]

Docusaurus builds a static site.
The output is just a static deployment, that you can merge the way you want with other static deployments from other tools if needed. This doesn't have to be a Docusaurus feature, you can just cp -R files manually after building them.

I don't know what you are trying to achieve here. It seems Dokka build API documentation where each api has its own url. You can embed a local iframe on a Docusaurus docs if you want, but can't tell for sure if it's what you are looking for. You'd have to draw some mockups and give a more precise spec for me to understand.

[slorber]

I would like to be able to add a static site generated by Dokka inside the docusaurus docs.

That is unclear to me what the outcome should look like. What are the urls you use to access your Dokkia site, and what is the layout should be.

It looks like Dokkia produces a site with a layout similar to Docusaurus (https://virtuslab.github.io/dokka-site/), so it is unclear what you want.

Do you want both Docusaurus and Dokkia sidebars to appear for example? 🤷‍♂️ That doesn't look like a great idea to me. First you need to be clear on what you are trying to achieve, and be able to communicate it properly to use. Please draw mockups if needed.

But I am not able to do that as if I add any static site inside docs, Docusaurus can't build.

You are not supposed to put a static site inside /docs: this folder is for docusaurus markdown files.

---

If you want to assemble your Docusaurus site with another static deployment, you have to put your other static site in:

• /static (recommended if you want to commit the Dokkia files)
• or the /build output (if you plan to not commit the Dokkia files).

At the end, the Dokkia files will be in /build anyway.

• /build/dokkia/v1 will be browsable at /dokkia/v1
• /build/dokkia/v2 will be browsable at /dokkia/v2

Now, you can add an iframe in respective Docusaurus docs if you want to embed those static deployments in a versioned docs page:

/docs/dokkia-api-wrapper.md:

# My Dokkia API

<iframe src="/dokkia/v2"/>

You can also add a link in your Docusaurus navbar to simply link to /dokkia/v2

---

Remember: it's just static files in the end.

If one tool provides abc.html, and another tool provides xyz.html, you can put all that in a single folder and deploy that folder.

Both /abc and /xyz will be published.

One tool doesn't understand the other, so if you want a deeper integration, you will have to build it yourself.

[JavierSegoviaCordoba]

The problem in placing the site in /static is I lose the versioning approach from Docusaurus.

I want to put a static site that can get versioned by Docusaurus inside /docs.

Docusaurus must be the tool that does the versioning, not Dokka or myself manually. Currently, that is impossible as placing a static site in docs fails.

[slorber]

The problem in placing the site in /static is I lose the versioning approach from Docusaurus.

No, you just have to handle the versioning yourself by using /static/dokkia/v1 and /static/dokkia/v2, as explained above.

I want to put a static site that can get versioned by Docusaurus inside /docs.

That is not a goal of Docusaurus to provide that feature, not now nor in the future.

If you want a thing that Docusaurus doesn't know anything about, to be integrated inside the versioned Docusaurus documentation, you will have to build the integration yourself, and figure out the edge cases.

Docusaurus must be the tool that does the versioning, not Dokka or myself manually. Currently, that is impossible as placing a static site in docs fails.

Docusaurus will never ever handle the Dokka versioning for you.

The docs folder is for markdown files, not for static Dokka files.

There's absolutely no plan to change that, unless you put effort in to convince us and can clearly explain technically how it should be done by proposing a clear feature design including a sample site content + expected output using mockups.

[JavierSegoviaCordoba]

I am seeing a common pattern in the Kotlin world in which projects use Docusaurus or Mkdocs to build the website but the Dokka API docs are added later as a static site, without versioning. Some examples:

• https://arrow-kt.io/
• https://square.github.io/okhttp/

I can understand this is outside of the Docusaurus scope anyway.

About the design, it should be simple:

• A flag to indicate that docs are going to be static sites. If this flag is enabled then clicking on any version in the dropdown menu will open that version site in another browser tab.
• Docusaurus would do its magic moving the folders with the docusaurus docs:version command.

[slorber]

The arrow dokka docs is not even on the same domain :
https://apidocs.arrow-kt.io

You can create one subdomain per dokka version and just create a drop-down with regular links for each dokka version. If you open links in browser tabs and don't expect the target to be a Docusaurus layout, then there's absolutely no reason to try integrating docusaurus with dokka, you can just link the 2 sites together like regular Internet sites.

Docusaurus does no magic at all with the versioning command, it only does a copy paste, nothing else that you can already do yourself today.