gistfile1.md

Development log (slash wiki)

I want to be able to write the kind of raw-thought, chronological, Markdown entries that I already do, and have them be public and logged. Basically, tumblogging/microblogging for projects instead of people.

• Git backed

  • Each change is a commit
  • No commit messages or any of that crap. Simple as possible.
  • Can be configured to commit to a branch of an existing repository (think ditz or GitHub Pages)

• Editing can be public (like a wiki), or disabled (edit via git push). No users or authentication.

  • Unwanted edits can always be reverted (git, yo)
  • Spam-prevention or blocking of visitors will have to come later, I suppose.
  • Perhaps expect users to run two instances, if they want authentication: one, editing disabled, and a second one on the same git repository behind HTTP auth?

• Entries can either be untitled (uncategorized), or appended to an existing titled ‘page.’

  • Untitled entries are appended to the ‘main’ page.
  • Entries are dated, and separated in their page by date/time headings (on the web, these should include relative views.)
  • After a certain, configurable amount of time, entries should become uneditable from the web- interface (as this is supposed to be a running log of development thoughts as they were at the time.)

• Entries are displayed in chronological order (newest at the bottom), but the page auto-scrolls to the latest (bottom) entry

  • This behaviour should be one of the very few configurable things

• The ‘untitled’ page is the landing page, and shows both untitled entries (in full) and the headings (usually edit-date/time) added to other pages (without their content), co-mingled in chronological order

  • This allows long-form content that the user doesn't want to clutter the main development-log with to exist in a different ‘namespace’, but still be discoverable from the landing page.
  • This also means that older content (i.e. pages that are no longer relevant) doesn't clutter up any central listing or navigation menu, without depending on curation.

• Simple design, hilighting the Markdown nature of the content (like Write.app)

Implementation thoughts

• First and foremost, this requires a way to map markdown files (categories) to/from titled ‘section’ representations

  • They must be representable as plain-text, because I want users to edit the files locally in a natural way (i.e. not as individual markdown files for each entry spread across folders or some shit.)

  • They must also be representable as sections, because the ‘headings’ of the sections matter to the web-interface, as do the commits that modify each section.

  • To map thusly, I think it will be easiest to maintain a mapping of lines of document to heading content. Then, when entry content changes, we can update the lines by searching for the known heading; and when the heading changes, we can update it by searching for known content.

    • (This requires that the user only ever modify either the heading or the content of a given entry in a given commit. This seems like a reasonable restriction upon the user.)

• Each ‘section’ needs a known creation-date, for both the “disable web-editing after x time” feature and for displaying relative-time on the web.

  • I suspect this will have to be maintained as the commits are parsed, from the original commit- author-date.

• Once the mapping is implemented as a library (and persisted somewhere; perhaps SQLite or Redis?), then we secondly need a tiny tool to preform the ‘meat’ of converting the Markdown content, via that mapping-metadata, to static webpages to be served.

  • This should be done automatically at git-receive-time (similar to git-blog). Perhaps the dynamic editing-part of the app below could also receive webhooks from GitHub?

• Finally, a tiny dynamic web-application to receive web-edits, apply them as git commits, and trigger the static recompilation. (Nothing except receiving edits from the web-interface, or receiving web-hooks, should generate dynamic content. CDN'able static content is king.)

Future features

• Spam prevention of some sort for wiki-style editing
• Automatic configuration of git hooks for lazy people
• Automatic configuration of GitHub webhooks (w/ the API) for lazy people
• ‘Sub-categories’ (pages with slashes in their name), and treating the relevant super-page the same way we handle the ‘untitled’ main page (showing entry-titles from subpages in the parent page, chronologically)
• Showing authors/contributors of a particular entry as GitHub avatars w/ links, if any of the authors have GitHub accounts. (Can do with the GitHub API?)
• Mapping of git blame-style annotations to lines of the output, and display-on-hover in the web interface (with links to the specific commit on GitHub, or to the author, for instance.)
• Filesystem-watcher for local editors, to automatically commit changes on file-save in the user's favourite editor.
  • Could do linting, trying to ensure that the new changes are commit-able in a way that makes sense to the web-interface (heading-changes, body-changes, and new entries, all saved separately; content appearing to be heading-separated entries; not trying to modify an old entry …)
  • If changes fail linting, commit them to a ‘failed’ branch on save, checking out that branch so the user can continue editing as they expect; and add a notice to the top of the file in question or something so the local user is aware.)
• Entry metadata support (for more complicated ‘themes’ or interfaces)?
• ACE web-editor with Markdown syntaxh-hilighting for entries