Trivial Server for Markdown via Express
A simple Express application that serves static markdown content transformed to HTML through marked and Handlebars. Intended to support light production use, it can be run stand-alone but is expected mostly to be used as middleware in a larger Express-based web site/application.
TSME can be installed either directly from the GitHub repository or as an NPM module. However you install, there are several directories in the TSME repository intended as examples of ways to structure the content that TSME serves, and not actually expected to be used outside of TSME development and test:
- You'll want your own
contentdirectory (which can be named whatever you want). This will contain content for individual pages in markdown (in a directory hierarchy that matches the URL scheme you want for your site), Handlebars templates used to serve the HTML generated from your markdown, and any custom assets that must be served along with your pages.
- There will have to be a
publicdirectory if you run TSME stand-alone or in an Express configuration that doesn't serve static assets using another component. TSME will try to serve non-markdown HTTP requests by looking in the
publicdirectory. The name and location of this directory is not currently configurable (see our To-Do list below). But, in a production environment, static assets should be served by a real web server or CDN prior to reaching TSME, anyway.
- You may want an
envsdirectory. TSME takes all of its configuration from environment variables, and reads them via the
- You may want a
bowerconfiguration. TSME includes very minimal example content, but the example Handlebars templates include Twitter
bootstrapfor page styling.
Installing from GitHub
TSME's dependencies and tool chain are intended to be familiar to anyone who has built Express web applications in the past.
- Clone TSME's git repository onto your local system
- In the repository,
npm installto load dependencies
npm startto start the example server locally
- navigating a browser to
http://localhost:3000/will give you the markdown from
Installing as an NPM
The TSME package can be installed simply by referencing it
Note that as part of the install,
in addition to loading other NPM packages that TSME uses,
npm install will run
bower to install the dependencies for TSME's
sample content, and configure the
directories to serve the sample content. These steps are
unnecessary when you're using TSME in a production environment,
but hopefully the additional dependency downloads will not
cause you problems.
- TSME assumes that markdown file names have the extension
- TSME uses Handlebars to load files from your
content/templatesdirectory, so naming there must conform to its conventions.
- TSME relies on the directory structure under
content/pagesmatching the URL structure of (the portion of) your site served by TSME.
- TSME will use a non-default Handlebars template for a markdown
- there is a template whose base name matches the name of the markdown file, and
- it is located in a directory under
content/templatesthat matches the path to the markdown file under
- Files from
content/pagesthat do not have matching Handlebars templates are served using
There are some configuration improvements that are obvious, but not immediately necessary for the use of TSME that is driving its development. Pull requests are always welcome, but particularly for these:
- Make the location of the
cover.cssfrom the bootstrap examples live on installation rather than having it committed in TSME's repository.
- Support an "installing in production" environment
variable that would cause
grunt install(used by
npm install) to skip
bowerand copying things around within TSME's directory structure.
- Include sample files in
envsfor production-like configurations to demonstrate asset loading from CDNs.
More significant planned development includes:
- Have a mechanism for setting a unique title for each page.
- Allow for there to be a
default.hbsfile in each directory under
content/templates, and look for those first when a markdown file doesn't have an exactly-matching Handlebars template.
- Have a wildcard-like mechanism allowing multiple markdown files to be matched with the same non-default template.