* Generalize the day-4 afternoon
This is in preparation for adding more options for this portion of the
course, and reflects an existing practice of substituting other
materials for this last half-day.
* address review comments
* Integrate GA4 code directly with `book.js`
The main advantage of this is that it simplifies the setup since we
can avoid the monkey-patching we did before.
A secondary advantage is that it should make things a little faster
since we avoid a request to the server on every page load.
* Remove unreachable return
* Watch all of `third_party`
It just occurred to me that we want to refresh the page in `mdbook serve` when anything changes in `third_party`.
* Remove `renderers` from `links` and `index` preprocessors
These two preprocessors are default preprocessors and controlled by
`build.use_default_preprocessors` not by `renders`.
* Fix the order of preprocessors
I was wrong about the order in #461.
* Remove `links` and `index` preprocessor lines
These default preprocessors are run by default.
---------
Co-authored-by: Jooyung Han <jooyung@google.com>
* Make i18n-helpers a requirement
* Skip mdbook-gettext for mdbook-xgettext
* Gettext finds PO file based on `book.language`
* Update workflow
No need to set `preprocessor.gettext.po-file`.
---------
Co-authored-by: Jooyung Han <jooyung@google.com>
svgbob translates `_text_` into `*text*`, which makes gettext fail to
translate paragraphs with `_text_`.
Co-authored-by: Jooyung Han <jooyung@google.com>
The picker is a drop-down menu using the same design as the theme
picker in the top-left.
There doesn’t seem to be an easy way to pass in a list of languages
and descriptions, so for now we’ll have to expand the menu by hand as
we add new languages. A comment has been added to `publish.yml` to
remind us of this.
This makes `mdbook` output a simple redirect at the location of the
old pages. I’ll try to add such pages when we shuffle around our
pages to make sure external links stay valid.
This fixes the 404 page on GitHub Pages: the default is `/`, but we’re
hosting the site from a subdirectory because of how the repository is
setup.
Fixes#178.
This implements a translation pipeline using the industry-standard
Gettext[1] system.
I picked Gettext for the reasons described in [2] and [3]:
* It’s widely used in open source software. This means that there are
graphical editors which will help you in editing the `.po` files. An
example is Poedit[4], which is available for all major platforms.
There are also many online systems for doing translations. An
example is Pontoon[5], which is used for the Rust website itself. We
can consider setting up such an instance ourselves.
* It is a light-weight yet structured format. This means that nothing
changes with regards to how you update the original English text. We
can still accept fixes and PRs like normal.
The structure means that translators can see exactly which part of
the course they need to update after a change. This is completely
lost if you simply copy over the original text and translate it
in-place in the Markdown files.
The code here only adds support for translations. They are not yet
tested, published or used for anything. Next steps will be:
* Add support for switching languages via a bit of JavaScript on each
page.
* Update the speaker notes feature to support translations (right now
“Speaker Notes” is hard-coded into the generated HTML). I think we
should turn it into a mdbook preprocessor instead.
* Add testing: We should test that the `.po` files are well-formed. We
should also run `mdbook test` on each language since the
translations can alter the embedded code.
Fixes#115.
[1]: https://www.gnu.org/software/gettext/manual/html_node/index.html
[2]: https://github.com/rust-lang/mdBook/pull/1864
[3]:
https://github.com/rust-lang/mdBook/issues/5#issuecomment-1144887806
[4]: https://poedit.net/
[5]: https://pontoon.rust-lang.org/
This implements a system for speaker notes via `details` elements and
some JavaScript. The general idea is
1. You add speaker notes to each page by wrapping some Markdown code
in `<details> … </details>`. This is a standard HTML element for,
well extra details. Browsers will render the element with a toggle
control for showing/hiding the content.
2. We inject JavaScript on every page which finds these speaker note
elements. They’re styled slightly and we keep their open/closed
state in a browser local storage. This ensures that you can keep
them open/closed across page loads.
3. We add a link to the speaker notes which will open in a new tab.
The URL is amended with `#speaker-notes-open`, which we detect in
the new tab: we hide the other content in this case.
Simultaneously, we hide the speaker notes in the original window.
4. When navigating to a new page, we signal this to the other window.
We then navigate to the same page. The logic above kicks in and
hides the right part of the content. This lets the users page
through the course using either the regular window or the speaker
notes — the result is the same and both windows stay in sync.
Tested in both Chrome and Firefox. When using a popup speaker note
window, the content loads more smoothly in Chrome, but it still works
fine in Firefox.
Fixes#53.
