Add notes about linking to oter pages

The Spanish translations use {{ page.baseurl }}/original/english/path so
that we don't have to change every url when we import a page after
translation.

1 files changed, 15 insertions, 0 deletions

diff --git a/README.md b/README.md
index a73be0eda..407ba08ec 100644
--- a/README.md
+++ b/README.md
@@ -76,3 +76,18 @@ node_modules/.bin/bower install
 
 Then use bower to install a new library and add it to the `Gruntfile.js`.
 
+## Linking to other pages
+
+Use `page.baseurl` to link to another page inside the repository.
+
+    <a href="{{ page.baseurl }}/english/path/to/page">Some Page</a>
+
+`page.baseurl` captures the current locale and inserts it in to the path if the
+user is not in the default locale (`EN`). Only use `site.baseurl` for linking
+to pages or assets that do not have a translation.
+
+_NOTE:_ `page.baseurl` does not include a trailing slash, so you must add this
+after the liquid tags (`}}/`). On the other hand, `site.baseurl` _is_ a slash,
+which is why you see the next part of the path hard up against the liquid tags
+(`}}assets`).
+