Website Progress

Dec 20 2011 by Garrett Serack @fearthecowboy
Tagsnews




I've been feverishly trying to write documentation this week ... and at the same time enhancing the DocPad-powered cms engine that's powering the CoApp.org website.

Layout

Over the last couple of days I've tweaked the layout of the website, and I think it's really starting to come together. Thanks to everyone on IRC who gave their feedback!

CMS Engine

The site is a statically-generated website that is based off of DocPad, but over the course of the last few days, I've significantly enhanced it with:

  • switched to GitHub-Flavored-Markdown for the Markdown processor

  • added the missing triple-backtick (```) syntax-highlighting format for color syntax highlighting of source code blocks (uses an online pygments webservice) -- this means no javascript in the browser to do syntax highlighting :)

  • enhanced the markdown language with a few new items (turning this slowly into what I call 'garrett-flavored-markdown' ):

  • image embedding with overflow wrapper so the image gets a scrollbar:

    ![alt-text](image-url)

  • video embedding, embeds videos with H.264 and webm codecs for HTML5 and a fallback to flash:

    % [width,height,posterimageurl,mp4url,webmurl]

  • HTML anchor support (for embedding the target of an anchor) :

    [text](anchor-id)

  • the ability to smuggle links into color-syntax highlighted code (see the example on the page http://coapp.org/reference/cli.html -- click on the --help in the text):

    «somecode«href»

Stuff to look at!

Please check out the developer articles I've started:

Getting setup with Git and GitHub
Setting up the development environment
Check out the source code

And the start of the reference work:

Common command-line reference -- usage information that is common to all/most CoApp command line tools
ptk.exe -- CoApp 'porting toolkit'

As you can see, I've started to make some 'standards' around what the content looks like, hopefully this will help people start to get a grip on the work that we've been doing.

I'd love your feedback, and even more, I'd love any help you can provide.

Playing with the CMS:

The only tools you need to play with the CMS engine is a Git and a text editor. (Not notepad!)

You can clone the repository:

404 Not Found

Error: Not Found

The requested URL / was not found on this server.

You can run the embedded mini-server by running the command:

404 Not Found

Error: Not Found

The requested URL / was not found on this server.

don't worry about any error message right now
you might get a firewall popup. Say yah, it's ok
press ctrl-c to stop the server (when you're done, or it does something goofy)

From there, you should be able to see the website in a browser: http://localhost:9778/index.html

Modify files in the ./src/ directory and below, and the server will automatically regenerate the site (and beep when it's done)... Lather, rinse, repeat.

If you've been putting off getting involved, now is a good time! Come check out the content (yeah, there's lots of 404s yet!) Feel free to fix them, put in placeholder pages, fix stuff, and send me a pull request on GitHub!

Turn lousy docs into good ones!

If you have any questions, ping me! Come to the IRC channel, just ... do SOMETHING!!

Garrett