Skip to content

Commit

Permalink
docs(series): add template types and priority system for series articles
Browse files Browse the repository at this point in the history
  • Loading branch information
welpo committed Oct 26, 2024
1 parent 05cc2b7 commit a7e695d
Showing 1 changed file with 30 additions and 1 deletion.
31 changes: 30 additions & 1 deletion content/blog/series/03-series-cheat-sheet/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ To force the feature on or off, use the `show_jump_to_posts` option in the `[ext

## Intro and Outro Templates

Series articles can have automatic introduction and conclusion sections. These are configured in your series' `_index.md`:
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") }}

Expand All @@ -56,6 +56,35 @@ default = "This article is part of the $SERIES_HTML_LINK series."
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:
Expand Down

0 comments on commit a7e695d

Please sign in to comment.