mirror page and localization

[johnnychen94]

A naive solution to support documentation with multiple languages, is to provide folder structure as follows:

docs/
├── Project.toml
├── build
├── make.jl
└── src
    ├── en
    │   └── index.md
    ├── index.md
    └── zh-cn
        └── index.md

In this way, https://johnnychen94.github.io/DemoCards.jl/dev/en and https://johnnychen94.github.io/DemoCards.jl/dev/zh-cn would point to contents written in different languages.

For terminology, I'll call en the main page, and zh-cn as the mirror page of en.

This solution works, but it is not working very nice. Here are some key challenges:

• there isn't a way to keep track of the contents to make sure they are updated. For example, it is very likely that mirror pages are out-dated because of various reasons. This is even harder if we consider the case that different pages might have different localization contents.
• mirror pages are usually developed distributedly in different repos. Usually, we can not assume that the main page is aware of the existence of mirror pages.

First, it is worth noting that, whether the multiple versions of the documentation are spread in different repos, or in one single big repo, or the mixture of them, it can be solved quite perfectly by #72.

To make sure whether contents are updated. We only need one more metadata in mirror pages. For example, in docs/src/zh-cn/config.json

{
    "upstream": "../en"
}

By doing this, we can link two page together, and generate a page mapping from en to zh-cn. Several tasks can be done with this map:

1. If a page is only available in en, it will be directly copied to zh-cn without modification. This often happens when the translation is incomplete.
2. given that each page contains a date timestamp, this page mapping can be used to dynamically generate an outdated warning/info at the beginning of each page of zh-cn.

Note that it only affects downstream mirrors (e.g., zh-cn), it won't affect upstream repo en. We could not assume that upstream is aware of the existence of downstream mirrors.

Of course, upstream can be remote page https://github.com/JuliaImages/juliaimages.github.io.git/[docs/src/pkgs] as is described in #72.

Note that this "upstream" configuration is per page. It is not a per-site upstream. To mirror the whole site, one has to organize the original site into multiple pages, and then configure multiple upstreams for them. For example, there can be three mirror pages for "tutorials", "pkgs", and "demos" in JuliaImages. Besides that, no synchronization is required and developers can be free to write content for better localization purposes (e.g., index.md). Again, given that #72 clones all repo in docs/.democards folder, the same repo won't be cloned multiple times.

[johnnychen94]

Actually, when this is done, I could just rename this package to AutoPage 😆