[Docs] migrate sphinx theme to shibuya

[hwhsu1231]

• Remove emscripten_sphinx_rtd_theme
• Pin sphinx-design==0.6.1, shibuya==2026.5.19
• Refactor home page with sphinx-design
• Internationalize strings in conf.py file
• Add edit this page to sidebar
• Use :layout: landing for front page

[sbc100]

Nice! Thanks for working on this.

I wonder if we can get a preview of what this looks like so we can take a look before landing this.

[hwhsu1231]

I wonder if we can get a preview of what this looks like so we can take a look before landing this.

I believe this Pull request previews is what you're looking for.

[sbc100]

I wonder if we can get a preview of what this looks like so we can take a look before landing this.

I believe this Pull request previews is what you're looking for.

Is that easy to setup? IIUC we don't currently use readthedocs.com at all today.

[hwhsu1231]

Not sure because I haven't tried it yet.

[sbc100]

I can try downloading this patch and take a look locally.

[hwhsu1231]

I wonder why these two checks failed after I removed the changes on .gitignore:

[sbc100]

Just a flaky test sadly. Re-running.

[hwhsu1231]

@sbc100

I just added the following new configuration for showing "Edit this page" on the sidebar:

html_context = {
    # Edit this page
    "source_type": "github",
    "source_user": "emscripten-core",
    "source_repo": "emscripten",
    "source_version": "main",
    "source_docs_path": "/site/source/",
}

Preview:

[sbc100]

Nice! Thanks again for working on this.

[sbc100]

site.zip

Uploaded a copy of the pre-built site.

There are a few things I'm not sure about still:

1. The "notes" seems to jump out way to much.
2. I think I prefered by previous "Fork my on github" ribbon over the new widget which shows stars a forks (seems a little busy)
3. The prominant Discussion link should probably no be linking to github disucssions (which I don't think we want to be using these days). Maybe it should link the mailing list or discord?
4. The front page doesn't looks a clean and clear. The notes there previously had to big button styling.
5. I'm not sure we want the "open in chatGPT" etc dropdown on each page.

[hwhsu1231]

I'm not sure we want the "open in chatGPT" etc dropdown on each page.

Sure. We can disable it by:

html_theme_options = {
  "show_ai_links": False,
}

[hwhsu1231]

The front page doesn't looks a clean and clear. The notes there previously had to big button styling.

Maybe we can specifically add :layout: landing to the top of the front page (/index.rst). This way, the front page will look a bit cleaner compared to the other pages.

Front Page:

Other Pages:

[sbc100]

I landed on the version bump separately BTW: #27042

[kripken]

Looks nice!

One note, maybe we can use the light theme by default? That would be less of a change compared to before, which makes it more familiar for users.

[hwhsu1231]

@kripken

One note, maybe we can use the light theme by default? That would be less of a change compared to before, which makes it more familiar for users.

That shouldn't be a problem because the default theme is "auto". Therefore, it will display light/dark themes based on the theme users are using.

[hwhsu1231]

@sbc100

The prominant Discussion link should probably no be linking to github disucssions (which I don't think we want to be using these days). Maybe it should link the mailing list or discord?

Just my personal opinion: I feel that keeping a forum-style discussion board that supports Markdown syntax is required.

As for the Discord link, I suggest we could use the discord_url theme option to display it:

html_theme_options = {
  "discord_url": "https://discord.gg/53u3EKq",
}

[hwhsu1231]

@sbc100

The "notes" seems to jump out way to much.

If you're talking about the two "notes" in the front page, maybe we can refactor them with .. admonition::?

Code:

.. admonition:: Interested to learn more?

  Read our :doc:`About page <docs/introducing_emscripten/about_emscripten>`!

.. admonition:: Ready to get started?

  :doc:`Download and install the SDK <docs/getting_started/downloads>` and then proceed to the :doc:`Tutorial <docs/getting_started/Tutorial>`!

Preview:

[hwhsu1231]

By the way, in my latest force-push (re-push), I also made this additional change to the front page:

.. rst-class:: lead

  Emscripten is a complete compiler toolchain to WebAssembly, using LLVM, with a special focus on speed, size, and the Web platform.

.. container:: buttons

  :doc:`Docs <docs/index>`
  `GitHub <https://github.com/emscripten-core/emscripten>`_

This was mainly inspired by the front page design of the Shibuya documentation:

[kripken]

Looks great to me!

@sbc100 , any more thoughts?

[sbc100]

I'd like to another interactive look first. I'll upload the zip file when I do.