---
tags: tauri-docs-2
---

# Tauri.app Rewrite: Page Types & URL Structure

[Tauri Documentation Ecosystem Evolution meta issue on GitHub](https://github.com/tauri-apps/tauri-docs/issues/1040)

## Open Items

- [ ] Can you have custom items in mdBook's config to globally enable/disable i18n?
- [ ] Rules for enabling/disabling i18n for docs need to be hashed out a bit more
- [ ] For building locales does that mean that every page for every locale needs to be rendered for SSR? Thinking of APIs specifically here if we keep the locale parameter in the URL. What build time and performance implications could this have?
- [ ] What sort of granularity do we want with versioning? Do we want similar to docs.rs? https://docs.rs/about/redirections
- [ ] Again, what would this look like from an overall build time perspective? Keep in mind if we do assets then they might get "versioned" as well and those add up quickly.
- [ ] We would also only i18n the latest docs most likely.
- [ ] Is this enough of a reason to look at doing SSR instead of SSG (https://docs.astro.build/en/core-concepts/routing/#server-ssr-mode)?
- [ ] We could do it selectively for only those "redirect" paths but still build via SSG for the actual target paths (https://docs.astro.build/en/guides/server-side-rendering/)

## Overview

There are four categories of content:

1. **Pages:** These are non-code specific items such as governance, branding, etc. and are stored on the `tauri-docs` repo. If more advanced layouts and rendering using Astro components for a specific guide are wanted (such as Getting Started guides) then those are also stored on the `tauri-docs` repo (although this should be avoided unless strinctly necessary).
2. **Docs:** These are technical guides that are focused around topics in a specific repo. The source docs are stored in the respective repo (such as `tauri` or `tauri-plugin-fs-watch`) and managed with mdBook. The `tauri-docs` CI pipeline will take care of copying and mirroring them onto the website based loosly on the mdBook config. The hierarchy should reflect that of mdBook's `SUMMARY.md` file.
3. **APIs:** API URL structure, page layouts, and rendering are defined within the `tauri-docs` repo. The source repo (such as `tauri` or `tauri-plugin-fs-watch`) just needs to provide the AST in JSON format (using `rustdoc-json` or `TypeDoc`'s AST output).
4. **Blog Posts:** Use for announcements and the like.

## Summary Structure

- Pages
- `tauri.app/[locale]/about`
- `tauri.app/[locale]/about/governance`
- Docs
- `tauri.app/[locale]/docs/[project]/[version]/...`
- `tauri.app/[locale]/docs/core/1/...`
- `tauri.app/[locale]/docs/tauri-plugin-fs-watch/1/...`
- APIs
- `tauri.app/[locale]/api/[project]/[version]/...`
- `tauri.app/[locale]/api/core-rust/1/window/struct.Window`
- `tauri.app/[locale]/api/core-js/1/notification`
- `tauri.app/[locale]/api/tauri-plugin-fs-watch/...`
- Blog Posts
- `tauri.app/[locale]/blog/[year]/[month]/[day]/[title]`
- `tauri.app/[locale]/blog/2022/12/09/tauri-mobile-alpha`

`[locale]`
: Value such as `es`, `nl`, or `zh-cn`. If not specified then it should be English. `en` should redirect to a URL without the locale.

`[project]`
: Value such as `core-rust`, `core-js`, or `tauri-plugin-fs-watch`. The exact value can be specified in the project mapping config in the `tauri-docs` repo.

`[version]`
: Value such as `1`, `1.1`, or `latest`. Aliases should be created and we should try to reach feature parity with docs.rs for the way versioning is handled (https://docs.rs/about/redirections). The versions that we opt-in to build, what its URL is, and which branch/tag/SHA should be used to build it can be specified in the project mapping config in the `tauri-docs` repo.

: **Note:** This does not mean that we'll have different versions for each minor and match version. Any URL more granular than a major version should just redirect to it's respective major version. i.e. `1.1` > `1`, `1.1.1` > `1`, `latest` > `1`, etc.

### Blog-Specific
`[year]`
: The 4 digit year for a blog post.

`[month]`
: The 2 digit month for a blog post (includes leading zero if applicable).

`[day]`
: The 2 digit day of the month for a blog post (includes leading zero if applicable).

`[title]`
: The title for the blog post. This will most likely be derived from the frontmatter.

## Locale & i18n

Note that the `[locale]` in a URL can be omitted and is treated as English. The `tauri-docs` repo will take care of synchronising any translations with Crowdin.

**Pages**
Will need to look into Astro and how to handle i18n there [`astro-i18next`](https://github.com/yassinedoghri/astro-i18next)

**Docs**
i18n can be enabled for a whole book using a custom item in mdBook's `book.toml` file (such as `enable-i18n = false`).

You can also selectively override this on a per-page basis with frontmatter (such as `enableI18n: true`).

**APIs**
While we currently have no plans to provide translations at the API level, we will still retain the `[locale]` path in the URL of an API page for the sake of consistency. This also gives us the flexibility in the future if we choose to do API translations.

**Blog Posts**
Currently no plans to provide translations for blog content but should follow the same approach as APIs explained above.

## Versioning

Alisas such as `latest` (and possibly `next` or `dev`) should be incorporated to enable easier linking.

**Pages**
Pages have no version by default. The only time a page should be versioned is if a more advanced doc (such as Getting Started) is to be written.

**Docs and APIs**
Both should follow the versioning of their respective source repo's package metadata. We should try to achieve parity with docs.rs versioning and redirects (https://docs.rs/about/redirections) but be sure to balance it to keep build time and size to a minimum.

Note that we will most likely just build major versions, not all minor and patch versions.

**Blog Posts**
Blog posts have no version.

## Project Mapping Config

This file drives a lot of the API and Doc generation. The exact place and format isn't known yet, but it should roughly contain the below information. This will be used to power the CI process as well as to render some UI labels.

[
    {
        // What will be rendered in the UI
        // Could also be taken from the package manafest, but we may
        // want this flexibility
        'label': 'Core Rust',
        
        // What the [project] component of the URL will be
        'url': 'core-rust',
        
        // Repo that holds the code
        'repo': 'tauri-apps/tauri',
        
        // The specific project type you'd like to create.
        // This can be `rust`, `typedoc`, or `mdbook` for now
        'project_type': 'rust',
        
        // Array of the different versions that should be generated
        // We may want to instead 'archive' old versions in the future
        // and not rebuild them every time we build
        'versions': [
            {
                // What it will be rendered as in the UI
                'label': '1',
                // The tag, branch, or SHA to be used
                'git_ref': 'v1',
                // The specific directory the manifest is contained in
                // We want to keep this in the version object so
                // that we could have flexibility if upstream repos
                // would change their directory structure
                'manifest_dir': 'core/tauri'
            },
            {
                'label': '2'
                'git_ref': 'v2'
                'manifest_dir': 'core/tauri'
            }
        ]        
    },
    {
        'label': 'Core JavaScript',
        'url': 'core-js',
        'repo': 'tauri-apps/tauri',
        'project_type': 'javascript',
        'versions': [
            {
                'label': '1',
                'git_ref': 'v1',
                'manifest_dir': 'tooling/api'
            },
            {
                'label': '2'
                'git_ref': 'v2'
                'manifest_dir': 'tooling/api'
            }
        ]        
    },
    {
        'label': 'Core Docs',
        'url': 'core',
        'repo': 'tauri-apps/tauri',
        'project_type': 'mdbook',
        'versions': [
            {
                'label': '1',
                'git_ref': 'v1',
                'manifest_dir': 'docs'
            },
            {
                'label': '2'
                'git_ref': 'v2'
                'manifest_dir': 'docs'
            }
        ]        
    }
]

### Answered Questions

- Is a repo mapping the right choice? Should we instead map to published crates and NPM package names?
- If so then maybe change URL schema to be `[prog_lang]/[package_name]` instead
- **Going to use a more flexible approach with a config file to let us manually define a mapping.**
- Some languages technically allow you to use the same function name but a different parameter signature in the same scope
- `fn send(file: String, private: Bool) -> ()` vs…
- `fn send(file: String) -> ()`
- **Nope, if a conflict happens then we can suffix the URL with `_1` for example.**
- How do we allow for i18n for each repo’s docs (even if they aren’t enabled by default)?
- **Have some config in the mdBook config to enable for a whole book and then frontmatter like `i18n-ready: true` to opt in for each page**
- Do the “Getting Started” guides belong in the `tauri` repo instead of the doc repo? Do we keep any prose in an upstream repo?
- **As much as possible should be in upstream repos. Some guides we may choose to opt-in to more advanced design and layouts and those would be stored in the `tauri-docs` repo (but this should be kept to a minimum).**
- How do we do versioning? Ideally I'd like to pull it from the respective package metadata instead of git tags, but that would require some more advanced checkout functionality during CI.
- **Going to use the project mapping config to give us some more flexibility around this**