Class: Docter::Page
- Inherits:
-
Resource::Base
- Object
- Resource::Base
- Docter::Page
- Defined in:
- lib/docter/page.rb
Overview
A single documentation page. Has title, content and ToC.
The content is HTML without the H1 header or HEAD element, ripe for including inside the template. The title is HTML-encoded text, the ToC is created from H2/H3 elements.
The content is transformed in three stages: # Transform from the original format (e.g. Textile, plain text) to HTML. # Parse the HTML to extract the body, title and ToC. The content comes from the body, less any
H1 element used for the title.
# Apply filters each time the content is retrieved (form #content).
Supported input formats include:
-
:plain – Plain text, rendered as pre-formatted (pre).
-
:html – The HTML body is extracted as the content, see below for ERB, title and ToC.
-
:textile – Converted to HTML using RedCloth. See below for ERB, code blocks, title and ToC.
-
:markdown – Converted to HTML using RedCloth. See below for ERB, code blocks, title and ToC.
EBR To support dynamic content some formats are run through ERB first. You can use ERB to construct HTML, Textile, Markdown or content in any format the page is using. This happens before the content is converted to HTML.
*Code blocks* Textile and Markdown support code blocks with syntax highlighting. To create a code block:
{{{!lang
...
}}}
You can use !lang to specify a language for syntax highlighting, e.g. !ruby, !sql, !sh. See Syntax for more information. The language is optional, code blocks without it are treated as plain text. You can also use syntax highlighting from HTML by specifying the class attribute on the pre element.
Title The recommended way to specify the page title is using an H1 header. Only one H1 header is allowed, and that element is removed from the content. Alternatively, you can also use the TITLE element, if both TITLE and H1 are used, they must match.
If none of these options are available (e.g. for :plain) the title comes from the filename, treating underscore as space and capitalizing first letter, e.g. change_log.txt becomes ‘Change Log’.
ToC The table of contents is constructed from H2 and H3 headers. H2 headers provide the top-level sections, and H3 headers are nested inside H2 headers.
The ToC links to each section based on the ID attribute of the header. If the header lacks an ID attribute, one is created using the header title, for example:
h2. Getting Started
becomes:
<h2 id='getting_started'>Getting Started</h2>
You can rely on these IDs to link inside the page and across pages.
Filters Runs the default chain of filters, or those specified by the :filters option. See Filter for more information. Filters are typically used to do post-processing on the HTML, e.g. syntax highlighting, URL rewriting.
Defined Under Namespace
Classes: ToCEntryForPage
Instance Attribute Summary
Attributes included from Resource::Reloadable
Instance Method Summary collapse
-
#content ⇒ Object
:call-seq: content => string.
-
#entries ⇒ Object
:nodoc:.
-
#id ⇒ Object
:call-seq; id => string.
-
#path ⇒ Object
:call-seq: path => filename.
-
#title ⇒ Object
:call-seq: title => string.
- #title=(title) ⇒ Object
-
#toc ⇒ Object
:call-seq: toc => ToC.
-
#toc_entry ⇒ Object
:call-seq: toc_entry => ToCEntry.
Methods inherited from Resource::Base
Methods included from Resource::Reloadable
#modified, #modified?, #reload, #to_s
Methods included from HTML
inner_text_from, regexp_attribute, regexp_element
Constructor Details
This class inherits a constructor from Docter::Resource::Base
Instance Method Details
#content ⇒ Object
:call-seq:
content => string
Returns the page content (HTML).
93 94 95 96 |
# File 'lib/docter/page.rb', line 93 def content load Filter.process(@content) end |
#entries ⇒ Object
:nodoc:
125 126 127 |
# File 'lib/docter/page.rb', line 125 def entries #:nodoc: toc.entries end |
#id ⇒ Object
:call-seq;
id => string
Returns fragment identifier for this page.
121 122 123 |
# File 'lib/docter/page.rb', line 121 def id @id ||= title.gsub(/\s+/, '_').downcase end |
#path ⇒ Object
:call-seq:
path => filename
Returns the path for this page. You can use this to link to the page from any other page.
For example, if the page name is ‘intro.textile’ the path will be ‘intro.html’.
113 114 115 |
# File 'lib/docter/page.rb', line 113 def path @path ||= File.basename(@filename).downcase.ext('.html') end |
#title ⇒ Object
:call-seq:
title => string
Returns the page title.
80 81 82 83 |
# File 'lib/docter/page.rb', line 80 def title load @title end |
#title=(title) ⇒ Object
85 86 87 |
# File 'lib/docter/page.rb', line 85 def title=(title) @title = title end |
#toc ⇒ Object
102 103 104 105 |
# File 'lib/docter/page.rb', line 102 def toc load @toc end |
#toc_entry ⇒ Object
:call-seq:
toc_entry => ToCEntry
Returns a ToC entry for this page. Uses the one_page
argument to determine whether to return a link to #path of the fragment #id.
134 135 136 |
# File 'lib/docter/page.rb', line 134 def toc_entry @toc_entry ||= ToCEntryForPage.new(self) end |