--- a/docs/api/02_components/02_sources.md	Tue Jul 28 21:36:00 2015 -0700
+++ b/docs/api/02_components/02_sources.md	Tue Jul 28 21:36:59 2015 -0700
@@ -2,5 +2,72 @@
 title: Page Sources
 ---
 
-`TODO`
+A page source is a component that retrieves pages from _somewhere_, and gives
+them to the rest of the application for processing. A typical blog would have 2
+sources: one for the blog posts, and one for the other pages (like the main
+page, an "_about_" page, some archives, etc.).
+
+To provide new page sources, you need to override the `getSources` method of
+your plugin, and return source _types_ (not instances!).
+
+
+```python
+class MyPlugin(PieCrustPlugin):
+    name = 'myplugin'
+
+    def getSources(self):
+        return [
+                MyCustomSource]
+```
+
+
+## Basic Implementation
+
+To implement a page source, you need to inherit from the `PageSource` class:
+
+```python
+from piecrust.sources.base import PageSource
+
+class MyCustomSource(PageSource):
+    def __init__(self, app, name, config):
+        super(MyCustomSource, self).__init__(app, name, config)
+        # Other stuff...
+
+```
+
+There are 3 methods you need to override for a basic, functioning page source.
 
+* `buildPageFactories(self)`: you should be returning a list of `PageFactory`
+  objects here -- one for each page inside the given source. Your source
+  instance has access to its configuration settings from the website's
+  `config.yml`, and to the current `PieCrust` application, among other things.
+  A `PageFactory` object describes how a page should be created. It has a
+  `ref_path` (_i.e._ a source-specific path which, for a simple source, could
+  just be the relative path of the page file inside the source's directory), and
+  some `metadata`. See "_Source Metadata_" later on this page.
+
+* `resolveRef(self, ref_path)`: you should return a tuple that describes the
+  page found at `ref_path`. The tuple contains the full path of the page file,
+  and the _source metadata_ for it.
+
+* `findPageFactory(self, metadata, mode)`: this is mostly useful when running
+  PieCrust as a dynamic CMS (which incidentally is also the case when previewing
+  with `chef serve`). Based on the _route metadata_ provided, the source is
+  expected to do its best to find a matching page, and return a `PageFactory`
+  for it.
+
+  The `mode` can either be `MODE_PARSING` or `MODE_CREATING`. The first mode
+  expects you to return a `PageFactory` for an existing page. That's the mode
+  that will always be given while running `chef serve`. The second mode expects
+  you to return a factory for a _non-existing_ page. That's the mode that will
+  be given when running `chef prepare`, _i.e._ when the application wants to
+  create a new page for a source, and needs to know exactly what file to create.
+
+
+## Source Metadata
+
+
+
+## Mixins
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/piecrust/osutil.py	Tue Jul 28 21:36:59 2015 -0700
@@ -0,0 +1,35 @@
+import os
+import sys
+import glob as _glob
+import unicodedata
+
+
+if sys.platform == 'darwin':
+    def walk(top, **kwargs):
+        for dirpath, dirnames, filenames in os.walk(top, **kwargs):
+            dirpath = _from_osx_fs(dirpath)
+            dirnames = list(map(_from_osx_fs, dirnames))
+            filenames = list(map(_from_osx_fs, filenames))
+            yield dirpath, dirnames, filenames
+
+    def listdir(path='.'):
+        for name in os.listdir(path):
+            name = _from_osx_fs(name)
+            yield name
+
+    def glob(pathname):
+        pathname = _to_osx_fs(pathname)
+        matches = _glob.glob(pathname)
+        return list(map(_from_osx_fs, matches))
+
+    def _from_osx_fs(s):
+        return unicodedata.normalize('NFC', s)
+
+    def _to_osx_fs(s):
+        return unicodedata.ucd_3_2_0.normalize('NFD', s)
+
+else:
+    walk = sys.walk
+    listdir = sys.listdir
+    glob = _glob.glob
+