docpad-archive / documentation

DocPad's Documentation. Cloned into the Bevry and DocPad websites for generation. Replaced by GitBook: https://docpad.bevry.me

ignored: true

Welcome to DocPad's Documentation Repository

It's pulled into the Bevry and DocPad websites and rendered by DocPad into beautiful documentation. Feel free to submit pull requests and post issues for it - one of our moderators will get to your changes as quickly as possible :)

Note on Links

Links inside the documentation will look like /docpad/config which within GitHub will go to the incorrect URL. This is because these links are short links that are expanded by DocPad during generation process. You can trial this by cloning out the DocPad Website yourself :)

Contributing

The Documentation Guidelines can be viewed on the Bevry Website

Maintainers

• Benjamin Lupton - @balupton
• Eduán Lávaque - @Greduan
• Paul Dowsett - @hal-gh
• Tony - @Zearin

License

Licensed under the incredibly permissive Creative Commons Attribution License
Copyright © 2012+ Bevry Pty Ltd
Copyright © 2011 Benjamin Lupton

documentation's Issues

Question about pull requests

Should it be "Each pull request should only alter one paragraph" or "Alter only one paragraph in each commit."? I tried doing a pull request per change, but it seems github merges all the changes into one pull request regardless.

Update node 0.10 recommendations to node 0.12

I am finding some situations in the docs where 0.10 is recommended. Based on docpad/docpad#913, I am preparing a pull request to update these places to recommend node 0.12 or io.js.

Use two spaces instead of one

This explains it: http://stevelosh.com/blog/2012/10/why-i-two-space/

I say it mainly for the example he gives about Vim's sentences.

Anyone have anything against this?

HTML fragment references do not work

I am checking the links in the documentation and none of the fragment references are working.

• Browser: Chrome 41
• OS: Linux / Fedora 20

Sometimes the site scrolls down / up rapidly when you click a fragment, so it is fairly obvious that something is broken.

Once I fix this, I will come back later and recheck the fragment references again to ensure that fragments are correct.

COMPARISON TABLE

Please update COMPARISON TABLE in https://docpad.org/docs/intro (row: Import pages from external services). jekyll support github gist via https://github.com/jekyll/jekyll-gist

Azure Deployment Information is dated

Currently on Docpad's Deploy Information page (https://docpad.org/docs/deploy), the provided Azure deployment information is out of date and not functional.

The issue stems from the installation script, which when running npm install fails due to the Node version defined within the package.json not being honored (it defaults to 0.6.x, which then has semver issues when installing Docpad)

Broken link

The link to the DocPad logo (which the user is supposed to download from d.pr while walking through the Beginner guide) is broken.

Extract parts of documentation from code comments

Currently, if there’s a change in the code, the documentation must be separately maintained.

For parts of the documentation (like the Beginner Guide), existing separately from the code is perfectly appropriate. But for other parts of the documentation—especially everything listed under “CORE”—I think it would be much better to find a way to maintain the documentation as part of the code, and maintain it there.

There are already lots of tools for doing this. I haven’t looked into it very deeply, but the Literate CoffeeScript functionality is particularly attractive, because it’s built into CoffeeScript itself, and uses Markdown. Another alternative would be to use the ### block-comment functionality of CoffeeScript in combination with another documentation-extracting tool would do the trick.

Thoughts on this? @bevry? @RobLoach? @balupton? @greduan?

Shoutout to @Zearin for his awesomeness!

Huge props to @Zearin for his recent pull requests and merges. Well done man! Great work.

'layout' directive is omitted in docs

Hi there,

I wonder why probably the most used meta directive 'layout' isn't described in metas docs?

And 'content' template data variable isn't described in template data docs.

Their existence & usage are obvious for experienced developers, but for Docpad novices their mentioning in docs would be useful.

better explanation for querying collections

• On https://docpad.org/docs/template-data#querying
  you don't see the findAllLive function of the database object - which is a common use case (in many skeletons projects you see this)
• The link to Query-Engine should go directly to the documentation: http://bevry.me/learn/queryengine-guide
• Add an hint/example, that you can query alll the meta data and special attributes (http://docpad.org/docs/meta-data) like relativeOutDirPath
• The query values seems to be strings, but thats wrong, they are regex - this should be mentioned due to avoiding problems like this: http://stackoverflow.com/questions/18375086/how-to-get-collections-from-sub-folder-in-docpad/18482027#18482027 or this http://stackoverflow.com/questions/15494422/collection-to-be-generated-from-all-the-sub-folders-into-one

Low priority: two initial slashes breaks the server

low priority

While checking links I noticed that two initial slashes breaks the static server. It happened to me on the docpad.org site, but I have not yet been able to reproduce on my own websites (e.g., rttpublications.org//)

I am not sure what the expected behavior would be, but it seems to me like someone should look at how fault tolerant the static server is.

Broken link

On https://docpad.org/docs/skeletons the first link in the documentation "Add it to the listing here." leads to a 404 page on github https://github.com/docpad/extas/edit/docpad-6.x/exchange.json

Include the raw plugin in the getting started guide

Or have a page after getting started called "performance optimisations and jedi tricks"

Add feature comparison table

It is is ridiculous that people still don't know how to compare us to other static site generators, or have given up on static site generators because all the crappy ones they've found don't have the features the need.

This is a huge failing on our part to market DocPad correctly.

Considering the rise of static site generators - http://staticsitegenerators.net - we need to do better at distinguishing ourselves. The intro page does well in this when comparing us to traditional CMS, but not when comparing us to other static site generators.

We should do up a feature comparison table. Rows should be features. Columns should be: Traditional CMS (Drupal, Wordpress), Traditional SSG (Jekyll), DocPad.

Something like this, with tooltips explaining the features and differences:

Feature	Usual CMS (Drupal, Wordpress)	Usual SSG (Jekyll)	DocPad
requires	cms developers	web developers	web developers
proficient in	months	days	days
plugin and extension system	yes	no	yes
asset pipeline	no	implicit & bundled	explicit & extendable
markup languages (markdown, rst, etc)	no	one bundled	yes via plugins
pre-processors (sass, less, etc)	no	no	yes via plugins
template engines (eco, jade, etc)	no	one bundled	yes via plugins
database querying	yes	no	yes via query-engine
layouts	yes	yes	yes
static website output	no	yes	yes
re-render each request	yes	no	possible (off by default)
extend the webserver	yes	no	yes
live reload	no	no	yes via plugin
partials	no	no	yes via plugin
database required	yes	no	no
import pages from file system	no	yes	yes
import pages from external database (mongodb, mysql, etc)	yes	no	yes via plugins
import pages from external services (tumblr, dropbox, github, etc)	no	yes	yes via plugins
import data from external services (atom, xml, json, etc)	no	no	yes via plugin
WYSIWYG editors	bundled	no	yes via plugins

Adding video tutorial links

I'm starting to put out these tutorials for DocPad, right now I've only got one.

Just for the future though, where would I go about adding these videos? Where would you prefer I add them @balupton?

Also where should I put a video request thingy? So that people can start requesting videos. Where do you prefer for that to be?

I'm planning on making a very extensive and complete video tutorial series so any suggestions that you have for videos are welcome. I plan on making the videos in a quality and amount that they themselves count as a documentation. :) Also any feedback on how to make the videos better is also welcome.

You can find all the videos I've done 'till now here: https://www.youtube.com/user/eduantech/videos

Add Ignore Includes Plugin

https://github.com/rantecki/docpad-plugin-ignoreincludes

Node links don't go anywhere.

https://github.com/bevry/docpad-documentation/blob/master/01-start/03-overview.html.md#the-packagejson-file

At the location above, the links to the Hands on Node training doesn't appear to go anywhere useful.

Add liferay as a DocPad partner?

@zenorocha I know that your company liferay does a lot with DocPad, would you like them recognised as a DocPad partner? If so, mind sending a pull request by adding a liferay file here:
https://github.com/docpad/documentation/new/master/partners

README: PULL REQUEST CRITERIA

Read the criteria here.

Todo:

• Rewrite this to be a lot more friendly, it's unnecessarily and unintentionally cruel right now
• Talk a lot more about how much we appreciate documentation changes, those who do them, as well as the problems we have faced with them, and how those problems are Bevry's fault for not having clear criteria in the first place, we are sorry
• Get more community support on this.

docpad upgrade doesn't work

I'm running Windows 7 64-bit and npm 2.5.1. When I do docpad upgrade it seems to work but then when I do docpad run it tells me a new version is available.

Document the generate options

Also applies to regenerateEveryOptions configuration option.

Options can be found here: https://github.com/bevry/docpad/blob/ccb91da643ebaa2a25524a281e86438fcf9aefd4/src/lib/docpad.coffee#L3281-L3320

Best place to put this is probably the API docs.

pt_BR translation

Can I translate the documentation to pt_BR language? I like to see it on my native language.

Document watchOptions

Necessary info here: docpad/docpad#749

Use `=` instead of `#{}` for Jade syntax

Here for example: http://docpad.org/docs/faq#what-is-a-templating-engine

Jade: #{Math.random()}

That is used primary for string interpolation.
For code you should use = or != for unbuffered code

see here: http://jade-lang.com/reference/#code

The Jade: #{Math.random()} example is confusing because:
when using #{} without having a tag on the left side - which is the use case in the example - then the result is absolute unexpected, see this gist: https://gist.github.com/timaschew/8355551

It's only expected when it is used as a content, for example:
div #{Math.random()}