In v2 of the course, I'd like to include an estimate of the time to be
spent on each segment in the Markdown file. I think a good place for
such metadata is in the frontmatter.
For review purposes, though, I just want to display that information.
So, this is a start at a new mdbook preprocessor that just separates out
the frontmatter and includes it in a `<pre>` block. Eventually, I'd like
to parse it and put the time in the speaker notes.
---------
Co-authored-by: Martin Geisler <martin@geisler.net>
- Morning of Day 1 still introduces the language and its high-level
goals/value proposition, and starts with the built-in data types Rust
provides, and how you define a function.
- Afternoon of Day 1 gets a front loading of the basic control flow
structures in Rust but not the more exotic ones.
- The exercises for day 1 afternoon will be the Luhn algorithm (where we
can match on digits and enums such as `Option`.
- Morning of day 2 still has discussion of memory management.
Fixes#510.
---------
Co-authored-by: Martin Geisler <mgeisler@google.com>
When building the book, mdBook will always generate an `index.html`
page for first page of the book. This meant that we had the same
content available under two different names:
- `welcome.html`: this is what the TOC would link to, and
- `index.html` or simply `/`: this is what search engines link to
Renaming the page and setting up a redirect should fix this confusion.
We still don’t have a good way of avoiding links to the `index.html`
page, but this should fix the first half of the problem.
I tested this for translations as well by building the output in a
subdirectory and serving the parent directory.
Part of #847.
Just like the Markdown files in #846, we cannot generate a redirect
for the LICENSE file this way. The broken link was fixed in #813, so
we should be fine here.
Those redirects don't actually work: they are not given a `Content-Type` by GitHub and so the browser doesn't threat them as HTML and won't follow any redirect.
* Adds a description of the async chat exercise
* Simplifies the use of Error in chat-async
* Links the solution to the async chat exercise
* Removes the elevator exercise
* Fix broken redirects
A few of these were wrong since they assumed the target path is
relative to the root of the course (the path is relative to the page
being redirected).
* Sort redirects
* Align outline with new spin-off course structure
With the new structure, the section on Android is a spin-off course
from the main 3-day course on Rust Fundamentals. The Bare-metal and
Concurrency days are spin-off courses in the same way.
* Explain new course structure
* Align Bare-Metal welcome page with other deep dives
* Merge Day 4 page into Course Structure page
* Remove Day 4 Welcome page
This aligns the Concurrency in Rust section with the Bare-Metal Rust
deep dive.
* Show subsections for Android deep dive
This aligns the Rust in Android section with the other deep dives.
* Clean up welcome page and README
We now cover async Rust and the course is no longer a four day course.
* Remove reference to the old Day 4
* Remove Day 4 references from exercises
* 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.
