How to format your pages
RDocSite uses the nearly standard RDoc markup. There’s a few very useful additions for generating websites.
Linking
RDocSite offers several ways to specify links between local pages and to external sites, too. It follows the ideas found in most wikis.
Local links
The nodes are identified by an ID, which was either set in the metadata section or extracted automatically from the file name. Actually, a file might by referenced by several IDs, if desired.
If the ID is a WikiName (i.e. begins with a number of uppercase letters, followed by lowercase letters and at least another uppercase letter), a link will be created right away, as is the case with typical Wikis. For example, RDocSiteDocumentationSummary takes you to the sitemap.
Sometimes, the ID is not a WikiName, or you want to use another label for the link; you can then use
site:someid
or
[[site:someid this is a link to the page referenced by someid]]
You can also create anchors for local (intra-node) linking, with
anchor:section1
and link to them with
[[link:#section1 go back to section 1]] no control over the label in this case: link:#section1
Resolution rules
RDocSite allows the site to have as complex a hierarchy as you want. You can also have several nodes with the same ID. Therefore, some rules are needed to specify the way local links are resolved. The following terminology is used:
| source node: | node where the link is made from |
| possible target node: | a node whose ID matches the one referenced by the source node. An ID might have several associated target nodes. The rules below specify which one the link will resolve to |
| parent node: | given a node nodename, its parent is the index node in the same directory, or the next index node higher in the hierarchy if nodename happens to be index or if index doesn’t exist in the same directory. |
| branch: | two nodes path1/node1.rdoc and path2/node2.rdoc are in
the same branch if the shortest of path1, path2 is a
prefix of the other. For example, given
foo/bar/baz/a.rdoc foo/a.rdoc these two nodes are in the same branch because foo is a prefix of foo/bar/baz. However foo/bar/baz/a.rdoc foo/bar/foobar/b.rdoc are in different branches. Another way to phrase it is that two nodes are in different branches if the common part of the paths is shorter than both paths. |
- target nodes in the same branch as the source node are preferred to those in parallel branches
- within a given branch, target nodes in the same level or lower than the source node are preferred to those higher than the source node
- amongst the preferred candidate nodes according to rule (2), the highest in the hierarchy is preferred
Consider the following hierarchy
foo.rdoc bar.rdoc a/foo.rdoc a/bar/foo.rdoc a/baz/bar.rdoc a/bar.rdoc b/foo/bar/baz/bar.rdoc
A link to foo like
[[site:foo link to foo]]
will be resolved to a/foo.rdoc in a/foo.rdoc and a/bar.rdoc (because of the second rule), and to foo.rdoc from the top-level foo.rdoc (because of the third).
Now consider what happens when a possible target is in a parallel branch: a link to bar from a/bar/foo.rdoc will resolve to a/bar.rdoc and not to a/baz/bar.rdoc; this is a consequence of the first rule.
Specifying the resolution scope
It is possible to override the third rule by specifying a (partial) path where the resolution should start from. For instance a link like
site:b/bar
in the top-level foo.rdoc will resolve to b/foo/bar/baz/bar.rdoc because the b branch was specified. If no bar.rdoc existed under b/, the link would resolve to the top-level bar.rdoc since it is in the same branch as b/ (first rule).
To summarize,
site:path/foo
makes RDocSite proceed as if the link had been requested from a source node under path/.
External links
The easiest way to link to external sites is simply inserting the URL, as in
you might want to go to http://raa.ruby-lang.org to find stuff
If the hostname starts with www., you can just use that
the main page for Ruby information and new releases is www.ruby-lang.org.
You can as well link to FTPs
there's stuff hidden in ftp.ruby-lang.org
and use the mailto: notation
don't hesitate to contact me at mailto:foo@rubyist.net
You can also specify the label to be used:
[[www.ruby-lang.org Ruby's main page]] [[http://raa.ruby-lang.org the RAA]]
There’s a few other useful external site references:
[[rubytalk:12345 link to some posting in ruby-talk]] [[rubygarden:HomePage link to a node in RubyGarden's wiki]] [[c2:FrontPage link to a node in the c2 wiki]] [[isbn:0201710897 link to a book by ISBN]]
Images
In order to link to an image, just insert its URL
http://www.rubygarden.org/ruby.gif
you can insert a local image with the following
img:somelocalimage.gif
It is also possible to link to an image, with
[[link:../someimage.gif link to some image]]
Metadata field expansion
It is possible to expand metadata fields in both rdoc and inc nodes (using the ExpandTagsFormatter, see the RDocSitePluginReference). Something like \expand:blah will be expanded to the contents of the metadata field blah. Note that this expansion is performed even when raw is set to yes.
| Table of contents |
| How to format your pages
Linking Images Metadata field expansion |