← Back to team overview

coapp-developers team mailing list archive

Re: Website documentation progress


Two more quick updates:

Garrett-flavored-markdown for images:
will now determine the url from just the filename (no path needed, it looks in the /src/static subdirectories for the image).


Garrett-flavored-markdown video tags:
can pass just the image filename  for the posterimageurl (like the image above. )

As well, I've put a redirect rule in the website so that http://coapp.org/videos maps to the Azure CDN at http://cdn.coapp.org/resources/  (which means that all the videos are now accessed thru the Azure Content distribution network across the globe :)


From: coapp-developers-bounces+garretts=microsoft.com@xxxxxxxxxxxxxxxxxxx [coapp-developers-bounces+garretts=microsoft.com@xxxxxxxxxxxxxxxxxxx] on behalf of Garrett Serack [garretts@xxxxxxxxxxxxx]
Sent: Thursday, December 22, 2011 6:26 PM
To: coapp-developers@xxxxxxxxxxxxxxxxxxx
Subject: Re: [Coapp-developers] Website documentation progress

I've done some more work on the website, just a couple of updates:

- I've added google +1 and facebook "like" buttons to pages and articles where appropriate.

- The videos actually work right on Firefox now, and should scale nicely to the size of the window.

- I've got google analytics back in there, so we can get some semblance of tracking info.

- a bunch of general cleanups in the code, removed some dead crap out of docpad.

- a page can now specifiy a 'docid' in the front matter (the stuff at the top between the --- and the --- lines ).  Once you put a docid in the header of a page, you can link to it using a markdown reference-style link, so that :

     if you run into trouble check the [ptk documentation][reference:ptk]

would render out as:

     if you run into trouble check the ptk documentation<http://coapp.org/reference/ptk.html>

The nice part about that, is that we can move the pages around and the links will still be correct.

I'm going to have it index the images as well, so you can just specify the name of the image, and it will find it and build the correct url (providing we don't run into duplicate filenames of images :)

From: coapp-developers-bounces+garretts=microsoft.com@xxxxxxxxxxxxxxxxxxx [coapp-developers-bounces+garretts=microsoft.com@xxxxxxxxxxxxxxxxxxx] on behalf of Garrett Serack [garretts@xxxxxxxxxxxxx]
Sent: Tuesday, December 20, 2011 5:46 PM
To: coapp-developers@xxxxxxxxxxxxxxxxxxx
Subject: [Coapp-developers] Website documentation progress

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.

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:

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

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

- 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)

Stuff to look at!
Please check out the developer articles I've started:

Getting setup with git and github<http://coapp.org/developers/git.html>
Setting up the development environment<http://coapp.org/developers/development-environment.html>
Check out the source code<http://coapp.org/developers/source-code.html>

and the start of the reference work:
Common command-line reference<http://coapp.org/reference/cli.html>
ptk.exe<http://coapp.org/reference/ptk.html> -- 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:
git clone git@xxxxxxxxxx:coapp/new_coapp.org.git

You can run the embedded mini-server by running the command:
cd new_coapp.org
     - 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:

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!!