aboutsummaryrefslogtreecommitdiffstats
path: root/pydis_site/apps/timeline/README.md
diff options
context:
space:
mode:
authorGravatar hedy <[email protected]>2024-03-23 19:48:41 +0800
committerGravatar ~hedy <[email protected]>2024-05-24 12:46:12 +0800
commit8eb4dc9ea279335fa6b7db1bc3cdfee5b914fd40 (patch)
tree2c06f40fa05a03f888609865c0a1a15f18b76da7 /pydis_site/apps/timeline/README.md
parentBump 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.md44
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.