Question about using Swift DocC archive with Docusaurus

[jkboxomine]

We're trying to use a Swift-DocC output as part of our static site generator built on Docusaurus.

The site is internationalized in English and one other language, but the API documentation is in English only. We're simply trying to show the English API documentation regardless of the language setting of the website.

We have a single DocC output placed under the /static directory, in a similar manner to API documentation for other platforms (generated by Dokka, TypeDoc, etc.), and the link to the documentation is configured with pathname:/// protocol on the sidebar file.

The content of DocC output is displayed properly in English mode. However, when we switch to the other language, the following occurs (Updated: 2022-08-11)

• In the local preview, a blank screen shows up with Uncaught SyntaxError: Unexpected token < error on the browser console.
• In the GitHub Pages hosting, "The page you’re looking for can’t be found." shows up.

When the language is switched, the base path is changed on the URL, from {docs.domain.com}/{sub-path} (English) to {docs.domain.com}/{lang_code}/{sub-path} (the other language), as expected. For the API documentation of other platforms, there's no issue with the display of content. For the DocC output, however, the issue described above occurs.

We think it might be due to the conflict between routing behavior of Docusaurus and DocC archive, but could not find an exact cause or workaround yet.

• If anyone succeeded in using Swift-DocC output with Docusaurus (i18n enabled), we'd appreciate it if you could share your experience or thoughts.
• As a workaround, if there's a way to force a specific link to be routed to the URL without lang_code when the website is set to non-English mode, let us know.

[slorber]

Hey

It's not very clear to me how you integrated Swift-DocC

Can you show me your live site, eventually source code? Because not seeing the problem myself makes it hard to debug, and I can't spend hours trying to figure out how you did encounter this problem in the first place.

What prevents you from creating a smaller repro with some fake HTML files instead of the Swift-DocC output? Is this issue really related to DocC in the first place?

[jkboxomine]

Is this issue really related to DocC in the first place?

Yes. Outputs from other API generation tools do not have this issue, which allow specifying index.html at the end of pathname:///. With DocC output, specifying index.html does not work due to some peculiarity, which is why sidebar.js should be configured as such.

I updated the issue description on the original posting, and created a test site and a GitHub repo for the reproduction of this issue. You can test the issue behavior by clicking "API Reference" link on the sidebar with the language set to English or French.

• Test page on GitHub Pages: https://jkboxomine.github.io/dcsrsTest/docs/intro
• GitHub repo: https://github.com/jkboxomine/dcsrsTest

I also reported this to Swift forum. If the issue cannot be mitigated on the Swift DocC side, any workaround on Docusaurus would be helpful.

[jkboxomine]

@slorber I received an answer from the maintainer of Swift-DocC plugin, which is the tool to transform the DocC Archive into a format for static hosting. He says we have to generate a separate set of documentation with a different base path configuration (including /lang_code in this case). I believe it would require us to place this in a different directory from the one for English, under static.

As far as I can tell, using a sidebar item with type: 'link' and pathname:/// protocol expects using a single instance of file set under static. If this is true, the current behavior of Swift-DocC plugin conflicts with the Docusaurus in terms of i18n requirement, making the Swift-DocC plugin output not usable on multi-lingual Docusarus sites.

I would appreciate it if you could confirm this or provide some other suggestion or workaround.

[jkboxomine]

@slorber In any case, we are aware that the root cause of the issue lies in the Swift-DocC plugin (and DocC archive), since its output is not a pure static HTML like the output of other API documentation generators. We just need evidence from both sides to prove that we must switch to an alternative method for iOS API documentation as long as we use Docusaurus and i18n.

[slorber]

hey @jkboxomine , this issue is extremely hard for me to decipher 😅 I'm not even sure I should read your wall of text because your analysis of the problem seems wrong to me.

Please give me a step by step guide to understand your problem. Make it crystal clear, no ambiguity, no possible wrong interpretation from my side, and eventually include screenshots.

---

I'm not 100% sure but what I think the problem is:

You have this sidebar external link:

    {
      type: 'link',
      label: 'API Reference',
      href: 'pathname:///api-reference/documentation/deckofplayingcards',
    },

• Step1: open https://jkboxomine.github.io/dcsrsTest/fr/docs/intro (french doc)
• Step2: click the "API reference" external link in the sidebar

Result:

https://jkboxomine.github.io/dcsrsTest/fr/api-reference/documentation/deckofplayingcards

Expected:

https://jkboxomine.github.io/dcsrsTest/api-reference/documentation/deckofplayingcards

---

Is that the problem you are reporting here?

If it's not the problem you are reporting: please provide me crystal clear reproduction instructions

---

For clarification, the API documentation itself is not internationalized, that is, in English only. We're just trying to show the English API documentation whether the website is set in English or in the other language.

If that's the case, you should decide on a unique URL for this English API doc to be hosted on. I believe you don't want/need this API doc to be accessible on multiple different URLs, and there's no value to make it available under a /fr/ baseurl => this would just be a duplicate.

But currently it fails when the website is set to the other language.

To me, this is a linking problem: the link rendered by Docusaurus on the French site is simply not what you want it to be: it shouldn't contain the /fr/ prefix for the French site. This has nothing to do with the Docusaurus / Swift-DocC integration, it is just not the external link you want.

This is not implemented yet, but we should enable you do solve this problem with some config:

    {
      type: 'link',
      label: 'API Reference',
      href: 'pathname:///api-reference/documentation/deckofplayingcards',
      autoAddBaseUrl: false,
    },

[jkboxomine]

@slorber Thanks for taking your time to summarize the issue. Your interpretation is correct and your suggested solution should work. What do I need to do to request adding the config described above?

[slorber]

It will be solved in #7949, and once it's merged you have to wait for 2.1 release or use a canary version

[jkboxomine]

Thank you for handling the request so promptly.