Class: Docter::Page

Inherits:
Resource::Base show all
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

#filename

Instance Method Summary collapse

Methods inherited from Resource::Base

#initialize

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).



114
115
116
117
 
# File 'lib/docter/page.rb', line 114

def content
  load
  Filter.process(@content)
end

#entries ⇒ Object

:nodoc:



146
147
148
 
# File 'lib/docter/page.rb', line 146

def entries #:nodoc:
  toc.entries
end

#id ⇒ Object

:call-seq;

id => string

Returns fragment identifier for this page.



142
143
144
 
# File 'lib/docter/page.rb', line 142

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’.



134
135
136
 
# File 'lib/docter/page.rb', line 134

def path
  @path ||= File.basename(@filename).downcase.ext('.html')
end

#title ⇒ Object

:call-seq:

title => string

Returns the page title.



101
102
103
104
 
# File 'lib/docter/page.rb', line 101

def title
  load
  @title
end

#title=(title) ⇒ Object 



106
107
108
 
# File 'lib/docter/page.rb', line 106

def title=(title)
  @title = title
end

#toc ⇒ Object

:call-seq:

toc => ToC

Returns the table of contents.



123
124
125
126
 
# File 'lib/docter/page.rb', line 123

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.



155
156
157
 
# File 'lib/docter/page.rb', line 155

def toc_entry
  @toc_entry ||= ToCEntryForPage.new(self)
end