From 2642cc42028b993846539120dadfa37b1d1b4762 Mon Sep 17 00:00:00 2001 From: ZzMzaw <89450172+ZzMzaw@users.noreply.github.com> Date: Thu, 31 Oct 2024 07:30:25 +0100 Subject: [PATCH] docs(series): clean up old series documentation --- .../series/01-series-introduction/index.md | 21 -- .../02-series-pages-organization/index.md | 21 -- .../series/03-series-cheat-sheet/index.md | 316 ------------------ content/blog/series/_index.md.old | 40 --- 4 files changed, 398 deletions(-) delete mode 100644 content/blog/series/01-series-introduction/index.md delete mode 100644 content/blog/series/02-series-pages-organization/index.md delete mode 100644 content/blog/series/03-series-cheat-sheet/index.md delete mode 100644 content/blog/series/_index.md.old diff --git a/content/blog/series/01-series-introduction/index.md b/content/blog/series/01-series-introduction/index.md deleted file mode 100644 index 4764e8ee8..000000000 --- a/content/blog/series/01-series-introduction/index.md +++ /dev/null @@ -1,21 +0,0 @@ -+++ -title = "An introduction to series" -date = 2023-05-21 -description = "This first article introduces how does series works and how to configure them." - -[taxonomies] -tags = ["showcase", "tutorial"] - -[extra] -series_template_variables = { position = "first", foo = "FOO!!!"} - -+++ - -{{ admonition(type="warning", icon="warning", title="IMPORTANT", text="This article has been introduced retroactively to showcase series.") }} - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. -Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. [^1] -Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. -Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - -[^1]: Lorem. diff --git a/content/blog/series/02-series-pages-organization/index.md b/content/blog/series/02-series-pages-organization/index.md deleted file mode 100644 index 149dc8c0b..000000000 --- a/content/blog/series/02-series-pages-organization/index.md +++ /dev/null @@ -1,21 +0,0 @@ -+++ -title = "How to organise a series' pages" -date = 2023-08-29 -description = "This second article focuses on how to organisation the pages of a series." - -[taxonomies] -tags = ["showcase", "tutorial"] - -[extra] -[extra.series_template_variables] -position = "second" -foo = "FOO FOO!!!" - -+++ - -{{ admonition(type="warning", icon="warning", title="IMPORTANT", text="This article has been introduced retroactively to showcase series.") }} - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. -Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. -Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. -Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. diff --git a/content/blog/series/03-series-cheat-sheet/index.md b/content/blog/series/03-series-cheat-sheet/index.md deleted file mode 100644 index 1a6cf4208..000000000 --- a/content/blog/series/03-series-cheat-sheet/index.md +++ /dev/null @@ -1,316 +0,0 @@ -+++ -title = "Series cheat sheet" -date = 2024-08-08 -description = "This last article provides an overview of series and describe all possible parameters." - -[taxonomies] -tags = ["showcase", "tutorial", "FAQ"] - -[extra] -series_template_variables = { position = "third", foo = "FOO FOO FOO!!!"} -toc = true -add_src_to_code_block = true -+++ - -## Quick Start - -1. Create a directory for your series. -2. Create `_index.md` in the series directory. -3. Set up the `_index.md` front matter: - - {{ add_src_to_code_block(src="series/_index.md") }} - - ```toml - title = "Learning Rust" - template = "series.html" - sort_by = "slug" - transparent = true - - [extra] - series = true - ``` - -4. Create your series articles in this directory. - -Want more? Keep reading! - -## Jump to Posts - -When a series has a description over 2000 characters, a "Jump to posts" link automatically appears next to the series title: - -##### TODO: Add screenshot with final design - -To force the feature on or off, use the `show_jump_to_posts` option in the `[extra]` section of your section (series) or in `config.toml`. This setting follows [the hierarchy](@blog/mastering-tabi-settings/index.md#settings-hierarchy). - -## Intro and Outro Templates - -Series articles can have automatic introduction and conclusion sections. These are configured in your series' `_index.md`. A basic example: - -{{ add_src_to_code_block(src="series/_index.md") }} - -```toml -[extra.series_intro_templates] -default = "This article is part of the $SERIES_HTML_LINK series." - -[extra.series_outro_templates] -default = "Thanks for reading part $SERIES_PAGE_INDEX of $SERIES_HTML_LINK!" -``` - -### Template Types - -The series system uses different templates based on an article's position in the series: - -- `next_only` - Used for the first article (has next article but no previous) -- `middle` - Used for articles with both previous and next articles -- `prev_only` - Used for the last article (has previous article but no next) -- `default` - Fallback template used when a specific position template isn't defined - -The system automatically determines which template to use based on the article's position. The templates are defined in the series configuration (`_index.md`), as `extra.series_intro_templates` and `extra.series_outro_templates`.: - -{{ add_src_to_code_block(src="series/_index.md") }} - -```toml -[extra.series_intro_templates] -next_only = "Welcome to part 1! Next up: $NEXT_HTML_LINK" -middle = "Previous: $PREV_HTML_LINK | Next: $NEXT_HTML_LINK" -prev_only = "The final chapter! Previously: $PREV_HTML_LINK" -default = "Part $SERIES_PAGE_INDEX of $SERIES_PAGES_NUMBER" -``` - -All templates are optional. Template selection follows a priority system: - -1. If a position-specific template exists (`next_only`, `middle`, or `prev_only`), it will be used -2. Otherwise, the `default` template is used -3. If no templates are defined at all, no series information will be displayed - -See the [template example](#template-example) for a more elaborate example. - -### Placement in Content - -By default: - -- Series introductions appear at the start of your article -- Series outro appears at the end (before footnotes, if any) - -You can control exactly where these appear using `` and `` in your Markdown: - -```markdown -This paragraph appears before the series introduction. - - - -Main content of the article. - - - -## Learning Resources - -Extra content… - -[^1]: Footnotes will always appear at the end. -``` - -## Variables - -Series templates use a flexible variable system that lets you: - -1. Reference series information (title, links) -2. Add navigation between articles -3. Show progress indicators -4. Include custom information using your own variables - -Variables are placeholders starting with `$` that get replaced with actual content when your site builds. For example, `$SERIES_HTML_LINK` becomes a clickable link to your series index page. - -There are three types of variables: - -- [**Basic Series Variables**](#basic-series-variables): General information about the series -- [**Navigation Variables**](#navigation-variables): Links to previous/next articles -- [**Custom Variables**](#custom-variables): Your own placeholders for additional information - -### Basic Series Variables - -{% wide_container() %} - -| Variable | Availability | Returns | Description | Example Usage | Example Output | -|----------|-------------|---------|-------------|---------------|----------------| -| `$SERIES_TITLE` | Always | Text | Plain text title of the series | `Part of $SERIES_TITLE` | Part of Learn Rust | -| `$SERIES_PERMALINK` | Always | Text | URL to series index | `[See all posts]($SERIES_PERMALINK)` | [See all posts](/series/learn-rust) | -| `$SERIES_HTML_LINK` | Always | HTML | Ready-to-use link to series | `Welcome to $SERIES_HTML_LINK!` | Welcome to Learn Rust! | -| `$SERIES_PAGES_NUMBER` | Always | Number | Total articles in series | `A $SERIES_PAGES_NUMBER part series` | A 5 part series | -| `$SERIES_PAGE_INDEX` | Always | Number | Current article's position | `Part $SERIES_PAGE_INDEX of $SERIES_PAGES_NUMBER` | Part 3 of 5 | -| `$SERIES_PAGES_OLIST` | Always | HTML | Ordered list of all articles | `Articles in series: $SERIES_PAGES_OLIST` | Articles in series:
  1. Current article
  2. Other articles
| -| `$SERIES_PAGES_ULIST` | Always | HTML | Unordered list of all articles | `Articles in series: $SERIES_PAGES_ULIST` | Articles in series: | - -{% end %} - -### Navigation Variables - -{% wide_container() %} - -| Variable | Availability | Returns | Description | Example Usage | Example Output | -|----------|-------------|---------|-------------|---------------|----------------| -| `$PREV_TITLE` | Previous exists | Text | Previous article's title | `Previously: $PREV_TITLE` | Previously: Setting Up Your Environment | -| `$PREV_PERMALINK` | Previous exists | Text | URL to previous article | `[← Back]($PREV_PERMALINK)` | [← Back](/series/learn-rust/setup) | -| `$PREV_HTML_LINK` | Previous exists | HTML | Ready-to-use link to previous | `Read $PREV_HTML_LINK first` | Read Setting Up Your Environment first | -| `$PREV_DESCRIPTION` | Previous exists | Text | Description of previous article | `Recap: $PREV_DESCRIPTION` | Recap: Setting up Rust | -| `$NEXT_TITLE` | Next exists | Text | Next article's title | `Next up: $NEXT_TITLE` | Next up: Advanced Patterns | -| `$NEXT_PERMALINK` | Next exists | Text | URL to next article | `[Continue →]($NEXT_PERMALINK)` | [Continue →](/series/learn-rust/patterns) | -| `$NEXT_HTML_LINK` | Next exists | HTML | Ready-to-use link to next | `Continue with $NEXT_HTML_LINK` | Continue with Advanced Patterns | -| `$NEXT_DESCRIPTION` | Next exists | Text | Description of next article | `Coming up: $NEXT_DESCRIPTION` | Coming up: Learn about Rust's advanced pattern matching features | - -{% end %} - -### First Article Reference - -{% wide_container() %} - -| Variable | Availability | Returns | Description | Example Usage | Example Output | -|----------|-------------|---------|-------------|---------------|----------------| -| `$FIRST_TITLE` | Always | Text | First article's title | `Start with $FIRST_TITLE` | Start with Introduction to Rust | -| `$FIRST_HTML_LINK` | Always | HTML | Ready-to-use link to first article | `Begin at $FIRST_HTML_LINK` | Begin at Introduction to Rust | - -{% end %} - -### Template Example - -{{ admonition(type="tip", title="HTML vs text variables", text="Use HTML variables (ending in `_HTML_LINK`) when you want ready-made links. Use text variables (ending in `_TITLE` or `_PERMALINK`) when you want more control over the formatting.") }} - -{{ add_src_to_code_block(src="series/_index.md") }} - -```toml -# Introduction. -[extra.series_intro_templates] -next_only = """ -Welcome to $SERIES_HTML_LINK! This $SERIES_PAGES_NUMBER-part series will teach you Rust from scratch. - -Up next: $NEXT_HTML_LINK - $NEXT_DESCRIPTION -""" - -middle = """ -📚 Part $SERIES_PAGE_INDEX of $SERIES_PAGES_NUMBER in $SERIES_HTML_LINK - -Previously: $PREV_HTML_LINK -Next up: $NEXT_HTML_LINK -""" - -prev_only = """ -Welcome to the final part of $SERIES_HTML_LINK! -New here? Start with $FIRST_HTML_LINK to build a strong foundation. - -Previously: $PREV_HTML_LINK -""" - -# Fallback template. -default = "This article is part of the $SERIES_HTML_LINK series." - - -# Outro. -[extra.series_outro_templates] -next_only = """ -Thanks for reading! 🙌 - -Continue your journey with $NEXT_HTML_LINK, where $NEXT_DESCRIPTION -Or check out the complete [$SERIES_TITLE]($SERIES_PERMALINK) series outline. -""" - -middle = """ ---- -📝 Series Navigation - -- Previous: $PREV_HTML_LINK -- Next: $NEXT_HTML_LINK -- [Series Overview]($SERIES_PERMALINK) -""" - -prev_only = """ -🎉 Congratulations! You've completed $SERIES_HTML_LINK. - -Want to review? Here's where we started: $FIRST_HTML_LINK -Or check what we just covered in $PREV_HTML_LINK. -""" - -# Fallback. -default = """ ---- -This article is part $SERIES_PAGE_INDEX of $SERIES_PAGES_NUMBER in $SERIES_HTML_LINK. -""" -``` - -### Custom Variables - -Series templates support custom variables for additional information you want to include across your series. The process takes two steps: - -1. First, define your **placeholders** in your series configuration (`_index.md`): - -{{ add_src_to_code_block(src="series/_index.md") }} - -```toml -[extra] -series = true -series_template_placeholders = ["$POSITION", "$TOPIC", "$DIFFICULTY"] -``` - -2. Then, in each series article, provide the values for these placeholders in `series_template_variables`: - -{{ add_src_to_code_block(src="series/article.md") }} - -```toml -[extra.series_template_variables] -position = "first" -topic = "Variables and Types" -difficulty = "Beginner" -``` - -### Using Custom Variables - -You can use your custom variables in any template, alongside the built-in variables: - -{{ add_src_to_code_block(src="series/_index.md") }} - -```toml -[extra.series_intro_templates] -default = """ -This is the $POSITION article in $SERIES_HTML_LINK. -Today's topic: $TOPIC -Difficulty level: $DIFFICULTY -""" -``` - -{{ admonition(type="warning", text="While placeholders are defined with uppercase (`$POSITION`), the variable names in `series_template_variables` must be lowercase (`position`).") }} - -### Example with Custom Variables - -{{ add_src_to_code_block(src="series/_index.md") }} - -```toml -# In the series configuration. -[extra] -series = true -series_template_placeholders = ["$LEARNING_TIME", "$KEY_CONCEPTS"] - -series_intro_templates.default = """ -📚 Part $SERIES_PAGE_INDEX of $SERIES_PAGES_NUMBER -⏱️ Estimated time: $LEARNING_TIME -🔑 Key concepts: $KEY_CONCEPTS -""" - -``` - -{{ add_src_to_code_block(src="series/02-learning-rust/index.md") }} - -```toml -# In an article of the series. -[extra.series_template_variables] -learning_time = "30 minutes" -key_concepts = "Functions, Error Handling, Pattern Matching" -``` - -This will output: - -```text -📚 Part 2 of 5 -⏱️ Estimated time: 30 minutes -🔑 Key concepts: Functions, Error Handling, Pattern Matching -``` - -{{ admonition(type="warning", title="Missing Variables", text="If you use a placeholder in your templates but don't provide its value in `series_template_variables`, the build will fail with an error listing the missing variables.") }} diff --git a/content/blog/series/_index.md.old b/content/blog/series/_index.md.old deleted file mode 100644 index e39c6bda2..000000000 --- a/content/blog/series/_index.md.old +++ /dev/null @@ -1,40 +0,0 @@ -+++ -title = "How to deal with series" -template = "series.html" -sort_by = "slug" -description = "This series explains how to properly configure a series." -transparent = true -insert_anchor_links = "left" - -[extra] -series = true -quick_navigation_buttons = true -show_jump_to_posts = true -post_listing_index_reversed = false - -series_template_placeholders = ["$POSITION", "$FOO", "$BAR"] -series_page_introduction = """ -You can put whatever you want in a custom description. - -**All** variable are accessibles, including custom ones. - -Markdown is rendered. -""" - -[extra.series_intro_templates] -prev_only = "Welcome back to $SERIES_HTML_LINK! This is article the $POSITION of $SERIES_PAGES_NUMBER, following $PREV_HTML_LINK." -next_only = "Welcome to $SERIES_HTML_LINK! This is the $POSITION article in a $SERIES_PAGES_NUMBER-part series." -middle = "Welcome to the $POSITION of $SERIES_PAGES_NUMBER articles in $SERIES_HTML_LINK. We previously covered $PREV_HTML_LINK." -default = "This article is part $SERIES_PAGE_INDEX of $SERIES_PAGES_NUMBER in the $SERIES_HTML_LINK series." - -[extra.series_outro_templates] -prev_only = "Check out the previous post in the $SERIES_HTML_LINK series: [$PREV_TITLE]($PREV_PERMALINK)." -next_only = "This is the start of the [series]($SERIES_PERMALINK). Continue with $NEXT_HTML_LINK!" -middle = "Previously: $PREV_HTML_LINK. Up next: $NEXT_HTML_LINK." -default = "This article is part of the $SERIES_HTML_LINK series." -+++ - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. -Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. -Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. -Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.