diff options
author | 2024-03-23 19:48:41 +0800 | |
---|---|---|
committer | 2024-05-24 12:46:12 +0800 | |
commit | 8eb4dc9ea279335fa6b7db1bc3cdfee5b914fd40 (patch) | |
tree | 2c06f40fa05a03f888609865c0a1a15f18b76da7 /pydis_site/apps/timeline/README.md | |
parent | Bump HassanAbouelela/actions from setup-python_v1.5.0 to 1.6.0 (#1326) (diff) |
Timeline: Migrate to Markdown source files - initial implementation
- The timeline app is introduced, moved from the home app.
- Add a basic README.md to illustrate the overall code breakdown of the
app as it is in the current stage.
- Two entries are added for now.
- Add ability to link headers using the slug portion of the filename.
- The way markdown files are fetched is similar to that of the resources
app - using the AppConfig ready() function, all resources are ensured
to be only fetched once when the app is first laoded.
I debated whether to introduce the new functionality in the home app
instead, without creating a new app. Eventually I decided extracting it
to a standalone app now is better as it allows easier extension of
functionality in the future. The home app can remain as it is to only
server the `/` homepage.
The timeline CSS is kept the same, as with the structure of the timeline
HTML template.
Once the CSS rewrite PR is merged, it's relatively easy to fix conflicts
here (again, since timeline is now its own app, with the CSS file and
HTML template moved - extra advantage).
References to `home:timeline` are updated to use `timeline:index`
throughout the codebase, as far as my ripgrep search could go.
The format of the markdown + YAML entries are still up for debate, so
I've only added the first two entries for now. They can be completely
overwritten in the future once the formats are decided by using a script
to convert all the data from my JSON file into individual markdown
files:
http://0x0.st/Xr78.txt
This link should last for at least a few months. (Originally saved on
https://paste.pythondiscord.com/KPJA, but it expires on 12th April 2024.)
Diffstat (limited to 'pydis_site/apps/timeline/README.md')
-rw-r--r-- | pydis_site/apps/timeline/README.md | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/pydis_site/apps/timeline/README.md b/pydis_site/apps/timeline/README.md new file mode 100644 index 00000000..a4272c4d --- /dev/null +++ b/pydis_site/apps/timeline/README.md @@ -0,0 +1,44 @@ +# The "timeline" app + +The [timeline page](https://www.pythondiscord.com/timeline/) on our website is +powered by this Django application. + +## The entries + +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 +`<date>_<name>.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 contains: +- YAML frontmatter. This 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. +- 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 `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 +testing](https://docs.djangoproject.com/en/dev/intro/tutorial05/) is a good +place to start. + +This application does not use the database and as such does not have models nor +migrations. |