Guides

PageNode extends AbstractNode
in package
implements RenderablePageInterface

FinalYes

Root AST node for a standalone page.

A page is authored in any supported documentation format (RST, Markdown, …), parsed from a dedicated source directory, compiled, and rendered as a self-contained HTML page. Pages are intentionally not part of the documentation tree: they have no toctree membership, no DocumentEntryNode in the ProjectNode, and no menu entries.

The output path for each page is declared inside the source file via a format-specific emitter of PageDestinationNode. If no destination is declared the source file path (without extension) is used as the fallback.

Table of Contents

Interfaces

RenderablePageInterface
Common contract for nodes that are rendered as standalone HTML pages outside the main documentation tree.

Properties

$classes  : string[]
$options  : array<string, scalar|scalar[]|null>
$value  : TValue
$filePath  : string
$headerNodes  : MetadataNode[]
Nodes that are rendered in the HTML <head> (metadata).
$outputPath  : string
Where this page should be written relative to the output root.

Methods

__construct()  : mixed
addHeaderNode()  : void
addMetaData()  : void
Attaches data about this node that is not part of its content.
from()  : self
getChildren()  : Node[]
Body nodes that make up the visible page content.
getClasses()  : string[]
getClassesString()  : string
getFilePath()  : string
Source file path relative to the pages source directory, without extension.
getHeaderNodes()  : MetadataNode[]
Metadata nodes that should be rendered inside the HTML <head>.
getMetaData()  : array<string, DataNode>
getNodes()  : F[]
getOption()  : mixed
getOptions()  : array<string, scalar|scalar[]|null>
getOutputPath()  : string
Output path relative to the output root, without extension.
getPageTitle()  : string|null
Returns the title string for use in the HTML <title> element, derived from the first {@see PageDestinationNode} or the first section title found in the header nodes.
getValue()  : TValue
hasOption()  : bool
setClasses()  : void
Normalizes class names following the rules of identifier-normalization
setOutputPath()  : void
setValue()  : void
toDocument()  : DocumentNode
withKeepExistingOptions()  : static
Adds $options as default options without overriding any options already set.
withOptions()  : static

Properties

$options

protected array<string, scalar|scalar[]|null> $options = []

$filePath read-only

private string $filePath

$headerNodes

Nodes that are rendered in the HTML <head> (metadata).

private MetadataNode[] $headerNodes = []

$outputPath

Where this page should be written relative to the output root.

private string $outputPath

Does not include the file extension (e.g. "about/index").

Methods

__construct()

public __construct(string $filePath[, Node[] $children = [] ]) : mixed
Parameters
$filePath : string

Source file path relative to the pages source directory, without extension (e.g. "about/index")

$children : Node[] = []

Parsed body nodes (sections, paragraphs, …)

addMetaData()

Attaches data about this node that is not part of its content.

public addMetaData(DataNode $data) : void

Rendered as a data-* attribute where the node's template asks for it. A name that is already taken gets the new values added to the ones it has, rather than replaced by them. DataNode

Parameters
$data : DataNode

getChildren()

Body nodes that make up the visible page content.

public getChildren() : Node[]
Return values
Node[]

getClasses()

public getClasses() : string[]
Return values
string[]

getClassesString()

public getClassesString() : string
Return values
string

getFilePath()

Source file path relative to the pages source directory, without extension.

public getFilePath() : string
Return values
string

getNodes()

public getNodes([class-string $nodeType = Node::class ]) : F[]
Parameters
$nodeType : class-string = Node::class
Return values
F[]

getOption()

public getOption(string $name[, TType|null $default = null ]) : mixed
Parameters
$name : string
$default : TType|null = null
Tags
phpstan-return

($default is null ? mixed|null: TType|null)

getOptions()

public getOptions() : array<string, scalar|scalar[]|null>
Return values
array<string, scalar|scalar[]|null>

getOutputPath()

Output path relative to the output root, without extension.

public getOutputPath() : string

Determined from PageDestinationNode if present, otherwise equals getFilePath().

Return values
string

getPageTitle()

Returns the title string for use in the HTML <title> element, derived from the first {@see PageDestinationNode} or the first section title found in the header nodes.

public getPageTitle() : string|null
Return values
string|null

getValue()

public getValue() : TValue
Return values
TValue

hasOption()

public hasOption(string $name) : bool
Parameters
$name : string
Return values
bool

setOutputPath()

public setOutputPath(string $outputPath) : void
Parameters
$outputPath : string

setValue()

public setValue(TValue $value) : void
Parameters
$value : TValue

withKeepExistingOptions()

Adds $options as default options without overriding any options already set.

public withKeepExistingOptions(array<string, scalar|null> $options) : static
Parameters
$options : array<string, scalar|null>
Return values
static

withOptions()

public withOptions(array<string, scalar|scalar[]|null> $options) : static
Parameters
$options : array<string, scalar|scalar[]|null>
Return values
static
On this page

Search results