While the entirety of p3k is not open source, I have open-sourced many of the components. I've chosen to provide components of my site rather than the whole thing because in reality nobody is going to want to use the exact same workflow I have built. Instead, components of my site can be re-used by others in their own way.
- Quill  - Posting interface for many kinds of posts
- Teacup  - food-tracking client
- Gramophone  - a podcast posting client
- Switchboard  - a PuSH hub
- Atlas  - APIs for looking up information about locations
- Compass  - a GPS tracking server
- Telegraph  - webmention sending API
- webmention.io - webmention receiver
- XRay  - extract post and author data from a page
- Monocle  - reader (not currently active)
- Watchtower - a minimal API to watch web pages for changes, similar to Superfeedr
- See also: p3k naming convention
- p3k-http - a small HTTP client
- p3k-utils - several helper functions for dealing with dates, timezones, URLs, and more
- p3k-websub - a library for subscribing to and publishing WebSub feeds
- php-mf2 - a PHP Microformats 2 parser
- mention-client-php - A PHP client to send webmentions and pingbacks
- php-comments - Helper for parsing and presenting comments from external sites
- link-rel-parser-php - Parse HTTP
Linkheaders into a structured format
- indieauth-client-php - Sample implementation and helper methods for an IndieAuth client
- date-formatter-php - Render dates and date ranges in a human-readable format, including proper microformats-2 markup
- emoji-detector-php - Finds all emoji in an input string and return information about each emoji character
- p3k-timezone - Find the timezone for a given latitude and longitude
- clone-media-fragment - enables YouTube-like time offset URLs for audio and video tags
- tantek/cassis - Used for truncating and ellipsizing post text
p3k has a built-in authorization endpoint, which supports customizing the scope granted, as well as restricting which "channels" apps can post to.
All content in p3k is stored as files on disk.
There is a main folder "posts" which contains individual files for each post as well as any associated files. Posts are stored in a folder structure by year/month/day/index.
The index increments with each new post created on that day. The index is not necessarily time-ordered, since quite often various import scripts create backdated posts after newer posts were already created.
Ultimately each post ends up with its own folder containing the primary post file
post.txt, and optionally a
public folder containing associated files. The web server serves files from this folder directly.
A post with a URL of:
will correspond with a storage file:
The image at the URL:
will be stored on disk as:
The contents of the
post.txt file is described below.
There is a YAML header block which contains some top-level properties that are core to p3k, such as published, type, content-type, and client-id. These are indexed in the database and control how the post is sorted and how it is rendered.
There is another top-level property called
properties which contains the Microformats2 vocabulary of all the post contents, with the exception of the
The header block is delimited by
..., and everything below the header is considered the
content Microformats2 property. The
content-type property notes the content type in order to indicate which renderer to use. (Either text, in which case a basic autolinker is used, Markdown which renders the Markdown as HTML, or HTML which outputs the contents directly without any processing.)
--- published: "2017-04-15T18:23:00-07:00" type: entry content-type: text/plain client_id: https://ownyourgram.com properties: category: indieweb location: type: - h-card properties: name: Migration Brewing Company latitude: 45.526300 longitude: -122.636451 locality: Portland region: Oregon country-name: USA syndication: https://www.instagram.com/p/BS7XoRCANxF/ photo: photo.jpg p3k-channel: - photos - primary ... Scheming. #indieweb
All values can be either arrays or single values, and there is some code to abstract reading and writing the values regardless of whether they are strings or arrays.
All properties in
properties can be read and written via Micropub requests.
Indexing and Caching
To render lists of posts, such as channels and tags, a database indexing strategy is used. Channels are top-level URLs such as /notes, /photos, /checkins. Tag pages live under the "tag" subdirectory, e.g. /tag/indieweb. The home page is actually just another channel named "primary".
Certain properties of each post are cached in a MySQL database and used when querying channel and tag pages.
- the published date, stored as UTC date with separate timezone offset
To generate a page such as the home page or a tag page, the database is queried and sorted by published date. The database returns the list of filenames, and then each post file is read from disk and rendered in a list.
The things I am currently implementing in p3k:
Error retrieving content from GitHub. Malformed JSON was returned from the API.
These are a collection of annoyances that have respective features / improvements. As their annoyance level bubbles to the top, they're likely to become concrete "Working On" tasks.
Blog posts in lists
Currently, any time you are looking at a list of posts on my site (my home page, a tag page, a search, etc), the full contents of articles is shown. This makes it hard to quickly scroll through the posts in the list. I'm considering switching back to showing just the name, summary and featured image. (This means I'll need to do a better job of setting featured images for my blog posts, but that would also be a good solution for generating the twitter/facebook meta tags too).
I'm not super happy with how to browse older content on my site. Mainly what's missing is a way to quickly browse past blog posts.
What I do like:
- Day permalinks: https://aaronparecki.com/2017/04/19/
- Month permalinks: https://aaronparecki.com/2017/04
- Year permalinks: https://aaronparecki.com/2017
The month permalinks are cute, but they aren't super actionable since there is no indication of *what* to find behind each icon. It might be nice to have some sort of additional summary of the month below or above the calendar. Maybe including things like:
- List of the name of each blog post that month
- Most common tags used in posts
- Summary of transport posts (number of miles biked, walked, number of flights, etc)
- Showcase events from the month
Here are some examples of blog post archive pages that I like. I might want to change my articles list to something more like these rather than showing the full contents of each post.
Venues / Checkins
- ✅ Checkin posts, e.g. https://aaronparecki.com/2017/04/19/9/
- Venue permalinks
- Find a good URL structure (I think I'm happy with the current solution)
- Need to store a mapping between Foursquare venues and my own permalinks, including handling what happens when Foursquare venues are merged/deleted
- Need a good venue search, or just defer to Foursquare checkins for now
- Replicate Foursquare lists on my site, along with a comment about why a venue is in that list
- Show venues clustered on a map
- Figure out what a venue permalink shows about the venue
- Comments from me about the venue? (e.g. foursquare tips)
- Collections the venue appears on
- A list of all my checkins at the venue? Last couple checkins? Paged feed of checkins?
- How to handle private venues? (Both from PESOSing foursquare checkins of private venues, and for checking in only on my site)
- Having real venue support would also make it easier to create events at locations, rather than just named places with no location info
These are taken from the Github issues "itching" label: https://github.com/aaronpk/p3k/issues
... and automatically generate a png thumbnail of the song
Need Further Thought
Since I carry an active GPS tracker at all times, I collect a large amount of location data. It currently provides data to location-tag all my posts, and sets the timezone of the posts to my local timezone. I do not have a feed of the raw location data available.
I'm considering publishing a new "location" post any time I change cities (or possibly also large neighborhood). Here is an example of publishing my city automatically to Facebook: http://www.flickr.com/photos/aaronpk/6962452588/
There are other non-venue locations I may want to publish, such as when I get into a neighborhood I haven't been to in a while. Ideally my phone would detect automatically when I've entered a new area or an area I haven't been to in a while. Probably I would want it to prompt me before publishing anything publicly. I could receive a push notification saying something like "It looks like you're in NW Portland for the first time this year! Publish this?" These posts are usually only interested when there is some additional information that provides context, such as "for the first time this year"