From 59d1ed30cb341d14670e0480fc5a444b34b0a598 Mon Sep 17 00:00:00 2001 From: Tom Preston-Werner Date: Wed, 31 Mar 2010 23:57:08 -0700 Subject: [PATCH] switch to endorse utf8 page names --- README.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a24cbcb8..6644d309 100644 --- a/README.md +++ b/README.md @@ -38,14 +38,16 @@ formats and allowed extensions is: Gollum detects the page file format via the extension, so files must have one of the supported extensions in order to be converted. -Page files may only contain lowercase alphanumeric characters and dashes, plus -the extension. For example: `tpw.md` and `apples-and-bananas.rst`. +Page file names may contain any printable UTF-8 character except space +(U+0020) and forward slash (U+002F). If you commit a page file with any of +these characters in the name and push the repository to GitHub, a commit will +be made on GitHub's side that replaces those characters with a dash (U+002D). Even though page files may be placed in any directory, there is still only a single namespace for page names, so all page files should have globally unique names regardless of where they are located in the repository. -The special page file `home.ext` (where the extension is one of the supported +The special page file `Home.ext` (where the extension is one of the supported formats) will be used as the entrance page to your wiki. If it is missing, an automatically generated table of contents will be shown instead. @@ -53,7 +55,7 @@ automatically generated table of contents will be shown instead. ## FOOTER FILES Footer files allow you to add a simple footer to your wiki. Footer files must -be named `_footer.ext` where the extension is one of the supported formats. +be named `_Footer.ext` where the extension is one of the supported formats. Footers affect all pages in their directory and any subdirectories that do not have footer files of their own. @@ -68,29 +70,28 @@ or JavaScript. These tags will be stripped from the converted HTML. To link to another Gollum wiki page, use the Gollum Page Link Tag. - [[Page Name]] + [[San Francisco]] The above tag will create a link to the corresponding page file named -`page-name.ext` where `ext` may be any of the allowed extension types. The +`San-Francisco.ext` where `ext` may be any of the allowed extension types. The conversion is as follows: - 1. Replace any non-alpha characters with a dash - 2. Lowercase all alpha characters + 1. Replace any non-printables, spaces, or slashes with dashes If you'd like the link text to be something that doesn't map directly to the page name, you can specify the actual page name after a pipe: - [[Page Name|page]] + [[SF|San Francisco]] -The above tag will link to `page.ext` using "Page Name" as the link text. +The above tag will link to `San-Francisco.ext` using "SF" as the link text. The page file may exist anywhere in the directory structure of the repository. Gollum does a breadth first search and uses the first match that it finds. Here are a few more examples: - [[Tom "TPW" Preston-Werner]] -> tom--tpw--preston-werner.ext - [[Quantum Physics|quantum]] -> quantum.ext + [[Tom "TPW" Preston-Werner]] -> Tom-"TPW"-Preston-Werner.ext + [[Quantum Physics|Quantum]] -> Quantum.ext ## ABSOLUTE VS. RELATIVE PATHS