Issue using DocC archive with React-based static site generator's routing

Development Swift-DocC
1

Hello,

We're trying to use the DocC archive as part of our static site generator based on Docusaurus. The site is internationalized in English and one other language.

When we put the DocC archive under the /static directory, the content is displayed properly in English version. However, when we switch to the other language, a blank screen shows up with "Uncaught SyntaxError: Unexpected token <" error on the browser console.

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 you succeeded in using DocC archive with a React-based static site generator (Docusaurus, Gatsby, Next.js, etc.) and its i18n behavior based on React routing, we'd appreciate it if you could share your experience or thoughts.

2

Hi Bryan, can you provide some more details about how you're building documentation for multiple languages? Do you have one DocC archive per language?

3

Hi Franklin,

We have a single DocC archive placed under the /static directory, in a similar manner to API documentation outputs for other platforms (generated by Dokka, TypeDoc, etc.).

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

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. But currently it fails when the website is set to the other language.

Thank you.

4

I found the following description on the DocC Plugin documentation.

1. What is the base path your documentation will be published at?

This differs based on the type of GitHub Pages site you have but is almost always the name of your GitHub repository.

Your documentation site will be published at something like

https://<username>.github.io/<repository-name>/...

and Swift-DocC needs to know about any base path after the github.io portion in order to correctly configure relative links. In the above case, that would be <repository-name>.

Does this suggest that it's not feasible to host a single instance of DocC archive on internationalized sites and view the content on other language modes, where an additional URL segment (lang_code) is bound to be added to the URL?

5

Sorry for the late response here. @ethankusters wrote the plugin and would be able to more help here. If the existing implementation doesn't allow for the way you'd like to organize your content, we can discuss how to resolve that.

6

Hi Franklin and @ethankusters,

I 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: Tutorial Intro | My Site
GitHub repo: GitHub - jkboxomine/dcsrsTest

The issue behavior on the original posting must be updated as follows:

The content of DocC output is displayed properly in English mode. However, when we switch to the other language, the following occurs:

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

Could you have a look at the issue and see if this can be solved?

7

Hi @sunburst,

Thank you for sharing the source code! I believe I see the issue.

The base path you pass to DocC needs to consider any sub-directories your DocC archive files are located in.

So for the English version of the documentation: the files are located here in an api-reference subdirectory and it looks like the base path is correctly set to /dcsrsTest/api-reference. The dcsrsTest component being the name of your GitHub repository and the api-reference component being the subdirectory your files are located in.

For the French version, the documentation is located at fr/api-reference. So you'll need to pass the fr path component as well. The base path you provide to Swift-DocC should be /dcsrsTest/fr/api-reference instead of /dcsrsTest/api-reference

- Ethan

2 Likes
8

Hi @ethankusters ,

Thank you for the answer. :slight_smile:

1 Like