Merge pull request #1293 from python-discord/feat/timeline-from-yaml

Markdown + YAML for the timeline

Author: wookie184

pydis_site/apps/home/README.md

@@ -1,8 +1,7 @@
 # The "home" app
 
 This Django application takes care of serving the homepage of our website, that
-is, the first page that you see when you open pythondiscord.com. It also
-manages the timeline page showcasing the history of our community.
+is, the first page that you see when you open pythondiscord.com.
 
 ## Directory structure
 

pydis_site/apps/home/urls.py

@@ -1,9 +1,8 @@
 from django_distill import distill_path
 
-from .views import HomeView, timeline
+from .views import HomeView
 
 app_name = 'home'
 urlpatterns = [
     distill_path('', HomeView.as_view(), name='home'),
-    distill_path('timeline/', timeline, name="timeline"),
 ]

pydis_site/apps/home/views.py

@@ -153,8 +153,3 @@ def get(self, request: WSGIRequest) -> HttpResponse:
         """Collect repo data and render the homepage view."""
         repo_data = self._get_repo_data()
         return render(request, "home/index.html", {"repo_data": repo_data})
-
-
-def timeline(request: WSGIRequest) -> HttpResponse:
-    """Render timeline view."""
-    return render(request, 'home/timeline.html')

pydis_site/apps/timeline/README.md

@@ -0,0 +1,45 @@
+# 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 file names have the format
+`<date>_<name>.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:
+- 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 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 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 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.
+
+This application does not use the database and as such does not have models nor
+migrations.

pydis_site/apps/timeline/__init__.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+
+from django.apps import AppConfig
+import frontmatter
+import markdown
+
+from pydis_site import settings
+
+
+ENTRIES_PATH = Path(settings.BASE_DIR, "pydis_site", "apps", "timeline", "entries")
+
+
+class TimelineConfig(AppConfig):
+    """AppConfig instance for Timeline app."""
+
+    name = 'pydis_site.apps.timeline'
+
+    def ready(self) -> None:
+        """Fetch all the timeline entries."""
+        self.entries = []
+
+        for path in ENTRIES_PATH.rglob("*.md"):
+            metadata, content = frontmatter.parse(path.read_text(encoding="utf-8"))
+
+            md = markdown.Markdown()
+            html = str(md.convert(content))
+
+            # Strip `.md` file extension from filename and split it into the
+            # date (for sorting) and slug (for linking).
+            key, slug = path.name[:-3].split("_")
+
+            icon_color = metadata.get("icon_color")
+            # Use the pydis blurple as the default background color.
+            if not icon_color or metadata["icon"] == "pydis":
+                icon_color = "has-background-primary"
+
+            entry = {
+                "key": key,
+                "slug": slug,
+                "title": metadata["title"],
+                "date": metadata["date"],
+                "icon": metadata["icon"],
+                "icon_color": icon_color,
+                "content": html,
+            }
+
+            self.entries.append(entry)
+
+        # Sort the entries in reverse-chronological order.
+        self.entries.sort(key=lambda e: e['key'], reverse=True)

pydis_site/apps/timeline/apps.py

@@ -0,0 +1,9 @@
+---
+title: Python Discord is created
+date: Jan 8th, 2017
+icon: pydis
+---
+
+**Joe Banks** becomes one of the owners around 3 days after it is created, and
+**Leon Sandøy** (lemon) joins the owner team later in the year, when the
+community has around 300 members.

pydis_site/apps/timeline/entries/2017-01-08_python-discord-is-created.md

@@ -0,0 +1,10 @@
+---
+title: Python Discord hits 1,000 members
+date: Nov 10th, 2017
+icon: fa fa-users
+icon_color: pastel-dark-blue
+---
+
+Our main source of new users at this point is a post on Reddit that happens to
+get very good SEO. We are one of the top 10 search engine hits for the search
+term "python discord".

pydis_site/apps/timeline/entries/2017-11-10_1000-members.md

@@ -0,0 +1,9 @@
+---
+title: Our logo is born. Thanks @Aperture!
+date: Feb 3rd, 2018
+icon: pydis
+---
+
+<p style="background-color: #7289DA; border-radius: 10px;">
+  <img style="padding-right: 20px;" src="https://raw.githubusercontent.com/python-discord/branding/main/logos/logo_banner/logo_site_banner.svg">
+</p>

pydis_site/apps/timeline/entries/2018-02-03_our-logo-is-born.md

@@ -0,0 +1,11 @@
+---
+title: PyDis hits 2,000 members; pythondiscord.com and @Python are live
+date: Mar 4th, 2018
+icon: fa fa-users
+icon_color: pastel-dark-blue
+---
+
+The public moderation bot we're using at the time, Rowboat, announces it will be
+shutting down. We decide that we'll write our own bot to handle moderation, so
+that we can have more control over its features. We also buy a domain and start
+making a website in Flask.