From 9e18aabe33e859c85745ac1ad2b83e313b7e0121 Mon Sep 17 00:00:00 2001 From: ~hedy Date: Fri, 24 May 2024 13:00:51 +0800 Subject: Better readme for timeline app --- pydis_site/apps/timeline/README.md | 41 +++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 20 deletions(-) (limited to 'pydis_site/apps') diff --git a/pydis_site/apps/timeline/README.md b/pydis_site/apps/timeline/README.md index a4272c4d..0b639261 100644 --- a/pydis_site/apps/timeline/README.md +++ b/pydis_site/apps/timeline/README.md @@ -8,35 +8,36 @@ powered by this Django application. Timeline entries are written in markdown files with YAML frontmatter under the `entries` directory. -Each file represents a timeline entry. The files are named with the format -`_.md`: -- `date`: The date is in the `YYYY-MM-DD` format, intended for easy sorting in - editor/shell command directory listings. It's also used to sort the entries - before rendering the timeline page. -- `name`: The name component is an arbitrary slug in **kebab-case**. This is used - for linking to individual timeline entries on the page, and will be set in - the `id` attribute. +Each file represents a timeline entry. The file names have the format +`_.md`, where: +- `date` is in `YYYY-MM-DD` for easy sorting of files in directory listings, + also used for sorting of the entries displayed on the timeline page. +- `name` is an arbitrary slug in `kebab-case`, used for linking to individual + timeline entries on the page, which will be set in the `id` attribute for each + timeline item. Each file contains: -- YAML frontmatter. This defines some metadata shown next to each entry in +- A YAML frontmatter, which defines some metadata shown next to each entry in the timeline, including: - - Date: User-facing date label. - - Icon: The CSS class to be used for the icon. Set to `pydis` to use the - pydis logo image. - - Icon color: The CSS class that sets the background color of the icon. Leave - empty if the pydis logo is used. + - `date`: User-facing date label. + - `icon`: The CSS class used for the icon, e.g. "fa fa-snowflake". Set to + `pydis` to use the pydis logo image. + - `icon_color`: The CSS class that sets the background color of the icon, e.g. + "pastel-red". List of available colors can be found in [the CSS + file](../../static/css/timeline/timeline.css). This can be omitted if the + pydis logo is used. - Markdown content. ## Directory structure -The app has a single view in `views.py` that takes care of reading the `.md` -files in the `entires` directory. This is a standard Django view, mounted in -`urls.py` as usual. +The app has a single view in `views.py` that renders the template using the list +of parsed entries from `apps.py`, which reads the markdown files on startup. +This is a standard Django view, mounted in `urls.py` as usual. -The `tests` directory validates that our redirects and helper functions work as -expected. If you made changes to the app and are looking for guidance on adding -new tests, the [Django tutorial introducing automated +The `tests` directory validates that the page renders successfully as expected. +If you made changes to the app and are looking for guidance on adding new tests, +the [Django tutorial introducing automated testing](https://docs.djangoproject.com/en/dev/intro/tutorial05/) is a good place to start. -- cgit v1.2.3