freegeekchicago/townsquare — Issue #98: Import Markdown docs on install
Author: eads
Created: 2012-01-06 05:49:48+00:00
State: open

I had a devious thought. Our source format for all long text content is Markdown. This means that if we had a way of importing Markdown from the filesystem, we could fairly easily maintain documentation that is easy to import during installation and maintain on the filesystem and in Drupal.

Such a system would consist of a custom module or integration that:

* Defines a "documentation" node type.
* Reads Markdown files (.md, .markdown) and converts them to documentation nodes based on a list of relative and absolute filesystem locations. (Optionally, the directory structure could be converted into a menu.)
* Tracks node->file associations, including database overrides of content and a mechanism to export to and import from the filesystem.
* Periodically check for modifications, addition, and removal of files from the specified locations.

The module needs some way of specifying the import source format Drupal should use, either via a dependency or configuration option.

The default FreeGeek Townsquare implementation should include a tiny module that configures the Markdown importer to grab everything under profiles/townsquare/doc and sets the site home page to /doc/home.

This comes dangerously close to replicating what does, but I think the core mechanism here is more elegant: it will jive better with distributed version control and the capabilities of systems like Github. With this system, regular users can improve the documentation, a project manager can export to code and commit the changes, and everyone gets to see a decent rendering of the documentation on the site itself and on Github/Bitbucket/et al.