Class: DocsUI::Page

Inherits:
Phlex::HTML
  • Object
show all
Includes:
DocsUI, PageHelpers, Phlex::Rails::Helpers::Request, Phlex::Rails::Helpers::Routes
Defined in:
app/components/docs_ui/page.rb

Overview

The base class for a hand-authored doc page. Subclasses set the title (and optional eyebrow/lead) and implement #content with the page body, composing the doc kit (Section/Prose/Code/Callout). Page renders it inside DocsUI::Shell with a consistent masthead.

class Views::Docs::Pages::Installation < DocsUI::Page
title "Installation"
eyebrow "Guide"
def lead = "Add the gem and render your first component."
def content
  render DocsUI::Section.new("Add the gem") { … }
end
end

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PageHelpers

#example, #md, #operation, #prose

Class Method Details

.description(value = nil) ⇒ Object

The per-page SEO/social description → DocsUI::MetaTags (via Shell). Set it for a hand-tuned description; when unset, Page derives one from #lead, so an existing page gets a sensible description for free. nil (no description, no lead) falls back to config.seo.description in MetaTags.



43
44
45
46
 
# File 'app/components/docs_ui/page.rb', line 43

def description(value = nil)
  @description = value if value
  @description
end

.eyebrow(value = nil) ⇒ Object 



34
35
36
37
 
# File 'app/components/docs_ui/page.rb', line 34

def eyebrow(value = nil)
  @eyebrow = value if value
  @eyebrow
end

.on_page(value = :__unset__) ⇒ Object

The "On this page" auto-TOC placement for this page. Defaults to the configured DocsKit.configuration.on_page_default; set false to opt out, or :panel/:toggle/:sidebar to override per page.



51
52
53
54
 
# File 'app/components/docs_ui/page.rb', line 51

def on_page(value = :__unset__)
  @on_page = value unless value == :__unset__
  defined?(@on_page) ? @on_page : DocsKit.configuration.on_page_default
end

.title(value = nil) ⇒ Object 



29
30
31
32
 
# File 'app/components/docs_ui/page.rb', line 29

def title(value = nil)
  @title = value if value
  @title
end

Instance Method Details

#content ⇒ Object

Override in subclasses with the page body.

Raises:

  • (NotImplementedError) 


92
93
94
 
# File 'app/components/docs_ui/page.rb', line 92

def content
  raise NotImplementedError, "#{self.class} must implement #content"
end

#lead ⇒ Object

Override in subclasses for the lead paragraph (optional).



89
 
# File 'app/components/docs_ui/page.rb', line 89

def lead = nil

#markdown_action? ⇒ Boolean

Whether to show the "Markdown" masthead action — the config knob (DocsKit.configuration.page_markdown_action, default true).

Returns:

  • (Boolean) 


82
 
# File 'app/components/docs_ui/page.rb', line 82

def markdown_action? = DocsKit.configuration.page_markdown_action

#view_template ⇒ Object 



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'app/components/docs_ui/page.rb', line 57

def view_template
  render DocsUI::Shell.new(
    title: self.class.title,
    description: self.class.description || lead,
    on_page: self.class.on_page
  ) do
    # data-md-skip drops this nav from the Markdown export — it's chrome, not
    # page content (DocsKit::MarkdownExport strips [data-md-skip]). The
    # "Markdown" action sits opposite "← Home"; it's chrome too, so it lives
    # inside the skipped nav and never appears in the .md twin.
    nav(class: "mb-6 flex items-center justify-between gap-4", data: { md_skip: true }) do
      a(href: root_path, class: "link link-hover text-sm opacity-70") { "← Home" }
      render DocsUI::MarkdownAction.new(request.path) if markdown_action?
    end

    render DocsUI::Header.new(self.class.title, eyebrow: self.class.eyebrow) do
      plain lead if lead
    end

    content
  end
end