Make the website static site generator distributable

[3w36zj6]

I am proposing this topic in English because I believe it will be of greater interest to people who do not speak Japanese.

The current website generator was developed for the Japanese localization project, but it could also be used for generating offline documentation or launching translation projects for other languages. However, to use it in these ways, you need to revert translated documents back to English and replace hardcoded metadata and Japanese text in the SSG, which is cumbersome.

Therefore, it would be helpful to modify the website SSG to be more generic and easily distributable.

Progress

• refactor: use metadata constants for absolute URLs in website #266
• chore: support configuration for deployment to custom base path #271
• refactor: move translations to singlefile #272
• docs: rewrite typst-docs-web README in English #275
• docs: translate SSG documentation comments to English #283
• feat: add translation switcher to website #284
• fix: correct the redirection to the official docs in SymbolsTemplate #294
• feat: add translation status display switcher #298
• chore: add metadata JSON file for website configuration #303
• chore: move SSG root to subdirectory for repository separation #307
• chore: make SSG favicon replaceable #315
• chore: make SSG Git submodule #316

[YDX-2147483647]

It's a mercy of you!
There was a discussion in https://github.com/orgs/typst-community/discussions/5 about translations in general. I guess you might be interested in.

Besides, moving website/ to a separate repository might help avoid volume expansion, though I'm not sure if website/ is the reason.

[Its-Just-Nans]

Hello,

You may be interested in

• https://github.com/Its-Just-Nans/typst.github.io
• https://typst-github-io.n4n5.dev/

Just a little question on the project, where does the templates come from? Scraping?

I'm also interested on why did you do build docs under "docs/":

• website/public/index.html
• https://github.com/typst-jp/typst-jp.github.io/blob/2314d2a27173fbe61e3414b395887f15158a714d/website/src/index.tsx#L29-L31

Note: the fact that the website cannot be on a subfolder by default is quite sad

[3w36zj6]

The TSX templates were created based on the documentation JSON type definitions (docs/src/model.rs) and inspired by the Jinja2 templates used in the Chinese community.

As for the static site's root being /docs/, this is mainly due to GitHub Pages constraints and also to match the routing structure of the official site (typst.app).

If there are users who would like to use this SSG for other projects, we would like to prioritize refactoring the currently hardcoded parts to make them more generic and reusable.

[Its-Just-Nans]

Okay so I guess the templates from the Chinese community are scrapped and edited from the official docs?

I'm not sure I get the Github Pages constraints but okay for following the routing

What hardcoded parts are you thinking of?
On my side I can list

• the links in the official json are all static (quite sad)
• https://github.com/typst-jp/typst-jp.github.io/pull/266
• the font

[YDX-2147483647]

refactoring the currently hardcoded parts to make them more generic and reusable.

The progress of the official project might need to be taken into consideration. Quoting Laurenz Mädje:

The conversion to Typst is blocked on proper multi-file HTML export which we pushed back (new goal for this feature is 0.15)
https://discord.com/channels/1054443721975922748/1399326777540608041/1399331170289848360

Normal Rust docs will stay as Markdown. Docs on #[elem] and #[func] might be changed to Typst, but maybe they'll stay as Markdown, too. The important part is that long-form docs and the orchestration becomes Typst and that it becomes possible to build the full docs with the open source tooling.
typst/typst#6704 (comment)

[Its-Just-Nans]

The progress of the official project might need to be taken into consideration. Quoting Laurenz Mädje:

Thanks for the link, I missed some discussions ^^

[3w36zj6]

Okay so I guess the templates from the Chinese community are scrapped and edited from the official docs?

Yes. The documentation content itself is open source. However, since the website design is not open source, we needed to build our own templates to respect the license¹.

the links in the official json are all static

Are you interested in handling multiple documentation JSON files on a single website? This approach could support things like switching between main and feature branch docs, or enabling i18n.

Footnotes

1. https://github.com/typst/typst/pull/3425#issuecomment-1954341630 ↩

[Its-Just-Nans]

Are you interested in handling multiple documentation JSON files on a single website? This approach could support things like switching between main and feature branch docs, or enabling i18n.

I feel like the typst team is gonna change the way there rendering docs with the html backend https://typst.app/docs/reference/html/. So for now, I'm not sure if implementing i18n would be a good idea.

[Its-Just-Nans]

After #266

Check again this multilang website

https://github.com/Its-Just-Nans/typst.github.io
https://typst-github-io.n4n5.dev/

To have a real website we need a language selector inside website/src/
Also search is still not working for now - maybe I will fix that EDIT done

[YDX-2147483647]

@Its-Just-Nans I appreciate your effort, but I suggest we continue the work in a dedicated repo.

There are many tricky subtleties in implementation, and I expect we'll discover more later. To name a few:

• refactor: use metadata constants for absolute URLs in website #266
  The /pagefind/ route (now fixed)
• chore: support configuration for deployment to custom base path #271
  Keeping old URLs under https://typst-jp.github.io/docs/ alive with proper redirection rules
• refactor: move translations to singlefile #272
  Word order. For example, entryの定義 vs. Definitions of entry.
  The current <code>{parent.name}</code>{menuTranslations.definitionOf} is not sufficiently expressive here.

If we develop in a dedicated a repo, we can ignore the details and fix them later.
However, if we push everything to this repo, we might bring unnecessary risks to https://typst-jp.github.io/docs/, and they will affect end readers directly.

Other possible benefits

In addition, using a dedicated repo has other benefits:

• https://typst-jp.github.io/docs/ is targeting typst v0.13.1, but it might be better for the the internationalized/distributable SSG to targerting the future/dev version of typst.

• https://github.com/typst-doc-cn/docs (typst-docs-l10n) is a wrapper over the official typst-docs crate. It paves the way to translating without touching rust files and drafting translations with LLM in batches.
  It's still experimental and not actively tested/used (the author is mainly working on tinymist), but possiblities can be explored.

I can watch https://github.com/Its-Just-Nans/typst.github.io if you plan to continue there.
Maybe creating a new repo under https://github.com/typst-jp or https://github.com/typst-community, if possible?

[Its-Just-Nans]

@Its-Just-Nans I appreciate your effort, but I suggest we continue the work in a dedicated repo.

Yes I think it can be a good idea. Only a repo named "docs" will have acces to "/docs"

If we develop in a dedicated a repo, we can ignore the details and fix them later. However, if we push everything to this repo, we might bring unnecessary risks to https://typst-jp.github.io/docs/, and they will affect end readers directly.

On my side I don't see why we cannot work on this repo for now, until the change

Other possible benefits
I can watch https://github.com/Its-Just-Nans/typst.github.io if you plan to continue there. Maybe creating a new repo under https://github.com/typst-jp or https://github.com/typst-community, if possible?

I agree that having a repo under typst-community organisation would be great, and for example with a domains like https://docs.typst.community/ but for now https://typst.community/ looks 404

[tingerrr]

@YDX-2147483647 Has made us aware of this issue, I've invited @Its-Just-Nans so they can deploy it on our domain, though we'll have to figure out what exact nameserver entries I'll have to add for it to points at the gh pages' deployment.

I'll add that the website looks stunning! Would be lovely for package/tool documentation :)