By Ryan Gray (email@example.com)
16 July 2012
A dynamic Markdown serving script.
You can have a whole site served on-the-fly with Markdown, including the index files.
PHP 5.3 or later
A PHP Markdown converter
Put the folder containing the files in a directory under your Apache webroot folder.
Get one of the PHP Markdown converters above, and put it under your webroot somewhere.
config.phpfile to set the
requirestatement to point to the PHP Markdown script.
Browse to the
doodad/testfolder, and you should get the test page.
$homeWebto the URL path from root to the folder you want to serve with this script.
You should copy and modify the
.htaccessfile in the
testfolder to this location. You can alternatively define this folder to be handled by this script in your Apache
httpd.conffile by defining a
<Location>for it and start with the directives in the sample
.htaccessfile in the
testfolder, adjusting them as needed.
The directives for the doodad folder being just under the web root:
DirectoryIndex index.php index.html index.md index.text # Path for PHP script needs to be from web root Action markdown /doodad/doodad.php AddHandler markdown .text .md
You can change the CSS location
The main CSS adds a lot of junk from my (unreleased) larger version of this project, and it also includes my Markdown CSS called Buttondown, which is optimized for Pandoc HTML output, but should still work well for basic output by other converters.
You'll notice in the
main.cssfile, it defines rules that look for words in image title attributes. You can add these to an image title to get some styling effects such as:
!(../css/linkTypeIcons/img/doc.png "box border shadow rounded")
It does co-opt the title attribute some, but you could just add these words at the end.
It also includes my
linkTypeIconsCSS rules that will automatically append an icon based on the file extension of a file you have linked to. You can add some of your own or just comment out the include in
There is also a
iOS.cssthat is included, but I'm still working on it. My CSS-fu is still weak.
You can enable the math option if you use PHP Markdown Extra Math as the PHP Markdown processor.
config.phpfor more details in the comments.
template.phpfile to your liking.
This is the template for the HTML page. It has a little PHP in it for the dynamic parts, but is mostly the static HTML for the generated HTML page.
For use in user folders:
If you put this in a folder under a user's web folder (to access with say
http://localhost/~joe/doodad/test, you will need to have configured Apache to be able to browse there.
For Mac OS X, at least, you will need to create a file in
usernameis the short username (e.g., "joe" in the example URL above). In that file, you should have at least:
<Directory "/Users/joe/Sites/"> AllowOverride All Order allow,deny Allow from all </Directory>
replacing "joe" with the appropriate username. As I understand it, this file should have root:wheel ownership, so do:
sudo chown root:wheel joe.conf
As a note, it seems that upgrading from Mac OS X 10.7 to 10.8 removed these user files I had previously set up, which made my user sites not work. As usual, it also replaced my modified
httpd.conffile and thus disabled PHP, but at least that is normal to have to uncomment when upgrading.
URL Query Options
Display the source Markdown text.
Display a navigation page relative to the current location. It has two options for recursing down directories and including files.
A nav link is built into the breadcrumb tail's "...". You can change the options it uses or include nav links with different options in your page or in your banner.
A version of Downdraft that uses Pandoc has other format options.
Just edit and create files in the folder being served, and they will be available right away. You can use relative links to link pages easily:
[Go up](..) [Sibling page](sibling.md) [Relative page](subfolder/foo.md)
.htaccess file defines
index.text as additional
DirectoryIndex, you can use a Markdown file with one of these
names (or adjust the
.htaccess file to the extensions you prefer) as a
directory index, so that you can make the whole site with just Markdown files.
This is useful if you make a folder for each page and make the Markdown file
index.md, then you can put any local images you need in the folder and just
link to them relative with no path:
The page will then have a URL that doesn't (need to) give the file name with
the markdown extension. This way, you can switch favorite extensions later, or
even later switch to having the
.md files statically converted to
files along side, and those would be served instead (since
index.md in the
DirectoryIndex definition. The URLs that people have
linked to would not need to change.