|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +module DocsUI |
| 4 | + # The marketing landing page — a hero (eyebrow + title + lead + optional install |
| 5 | + # snippet + CTA buttons), a feature-card grid, and a registry-grouped |
| 6 | + # documentation index — rendered inside DocsUI::Shell. Every consuming site was |
| 7 | + # hand-rolling this; drive it from config instead: |
| 8 | + # |
| 9 | + # # config/initializers/docs_kit.rb |
| 10 | + # DocsKit.configure do |c| |
| 11 | + # c.landing.eyebrow = "Developer Docs" |
| 12 | + # c.landing.title = "Jobs & events on **Postgres**" # ** ** → primary color |
| 13 | + # c.landing.lead = "PostgreSQL-native jobs + event bus for Rails." |
| 14 | + # c.landing.install = { code: 'gem "pgbus"', filename: "Gemfile", lexer: :ruby } |
| 15 | + # c.landing.ctas = [{ label: "Get started", href: "/docs/overview", style: :primary }] |
| 16 | + # c.landing.features = [{ icon: "database", title: "One database", body: "No Redis." }] |
| 17 | + # end |
| 18 | + # |
| 19 | + # # a controller that includes DocsKit::Controller |
| 20 | + # def show = render_page(DocsUI::Landing.new) |
| 21 | + # |
| 22 | + # Everything is optional: with an empty c.landing it still renders a minimal hero |
| 23 | + # (the brand name + the doc index), never a broken page. The doc index is built |
| 24 | + # from DocsKit.configuration.nav_groups — the same registry the sidebar uses — so |
| 25 | + # it never drifts from the authored pages. |
| 26 | + # |
| 27 | + # It IS a full document (composes Shell), so a controller renders it with |
| 28 | + # `layout: false`, exactly like DocsUI::Page (DocsKit::Controller#render_page |
| 29 | + # does this). The `.md`/`.text` twin of the landing works too — MarkdownExport |
| 30 | + # walks the same #docs-content region Shell stamps. |
| 31 | + class Landing < Phlex::HTML |
| 32 | + include Phlex::Rails::Helpers::Request |
| 33 | + |
| 34 | + def view_template |
| 35 | + render DocsUI::Shell.new(title: landing.eyebrow || config.brand) do |
| 36 | + div(class: "mx-auto max-w-5xl") do |
| 37 | + hero |
| 38 | + feature_grid |
| 39 | + doc_index |
| 40 | + end |
| 41 | + end |
| 42 | + end |
| 43 | + |
| 44 | + private |
| 45 | + |
| 46 | + def config = DocsKit.configuration |
| 47 | + def landing = config.landing |
| 48 | + |
| 49 | + # --- hero ---------------------------------------------------------------- |
| 50 | + |
| 51 | + def hero |
| 52 | + div(class: "flex flex-col gap-6") do |
| 53 | + eyebrow |
| 54 | + heading |
| 55 | + lead |
| 56 | + install_snippet |
| 57 | + ctas |
| 58 | + end |
| 59 | + end |
| 60 | + |
| 61 | + def eyebrow |
| 62 | + return unless (text = landing.eyebrow) |
| 63 | + |
| 64 | + p(class: "text-sm font-medium uppercase tracking-wide text-primary") { text } |
| 65 | + end |
| 66 | + |
| 67 | + # The <h1>. A **run** wrapped in double asterisks renders in the primary color |
| 68 | + # (the one bit of markdown we honor, so a site can accent a word without HTML). |
| 69 | + def heading |
| 70 | + h1(class: "text-4xl font-bold tracking-tight md:text-5xl") do |
| 71 | + (landing.title || config.brand).to_s.split(/\*\*(.+?)\*\*/).each_with_index do |part, index| |
| 72 | + next if part.empty? |
| 73 | + |
| 74 | + index.odd? ? span(class: "text-primary") { part } : plain(part) |
| 75 | + end |
| 76 | + end |
| 77 | + end |
| 78 | + |
| 79 | + def lead |
| 80 | + return unless (text = landing.lead || config.tagline) |
| 81 | + |
| 82 | + p(class: "max-w-2xl text-lg text-base-content/70") { text } |
| 83 | + end |
| 84 | + |
| 85 | + def install_snippet |
| 86 | + return unless (snippet = landing.install_snippet) |
| 87 | + |
| 88 | + render DocsUI::Code.new(snippet[:code], lexer: snippet[:lexer], filename: snippet[:filename]) |
| 89 | + end |
| 90 | + |
| 91 | + def ctas |
| 92 | + buttons = landing.ctas |
| 93 | + return if buttons.empty? |
| 94 | + |
| 95 | + div(class: "flex flex-wrap items-center gap-4 pt-2") do |
| 96 | + buttons.each { |cta| cta_button(cta) } |
| 97 | + end |
| 98 | + end |
| 99 | + |
| 100 | + def cta_button(cta) |
| 101 | + attrs = { href: cta.href, class: "#{cta.btn_class} gap-2" } |
| 102 | + if cta.external? |
| 103 | + attrs[:target] = "_blank" |
| 104 | + attrs[:rel] = "noopener" |
| 105 | + end |
| 106 | + a(**attrs) do |
| 107 | + render DocsUI::BrandMark.new(cta.icon, class: "size-4", label: cta.label) if cta.icon |
| 108 | + plain cta.label |
| 109 | + end |
| 110 | + end |
| 111 | + |
| 112 | + # --- feature grid -------------------------------------------------------- |
| 113 | + |
| 114 | + def feature_grid |
| 115 | + features = landing.features |
| 116 | + return if features.empty? |
| 117 | + |
| 118 | + div(class: "mt-12 grid gap-4 sm:grid-cols-2") do |
| 119 | + features.each { |feature| feature_card(feature) } |
| 120 | + end |
| 121 | + end |
| 122 | + |
| 123 | + def feature_card(feature) |
| 124 | + div(class: "rounded-box border border-base-300 bg-base-200/40 p-5") do |
| 125 | + div(class: "flex items-center gap-2 text-primary") do |
| 126 | + render DocsUI::Icon.new(feature.icon, class: "size-5") if feature.icon |
| 127 | + span(class: "font-semibold text-base-content") { feature.title } |
| 128 | + end |
| 129 | + p(class: "mt-2 text-sm text-base-content/70") { feature.body } if feature.body |
| 130 | + end |
| 131 | + end |
| 132 | + |
| 133 | + # --- documentation index ------------------------------------------------- |
| 134 | + |
| 135 | + # The registry-grouped page index. nav_groups is the three-level Hash the |
| 136 | + # sidebar renders ({ heading => { subgroup => [NavItem] } }); the landing |
| 137 | + # flattens each heading's items into a linked column. |
| 138 | + def doc_index |
| 139 | + return if !landing.doc_index? || (groups = flattened_nav).empty? |
| 140 | + |
| 141 | + div(class: "mt-16") do |
| 142 | + h2(class: "text-sm font-semibold uppercase tracking-wide text-base-content/50") { "Documentation" } |
| 143 | + div(class: "mt-6 grid gap-8 sm:grid-cols-2") do |
| 144 | + groups.each { |heading, items| doc_index_group(heading, items) } |
| 145 | + end |
| 146 | + end |
| 147 | + end |
| 148 | + |
| 149 | + def doc_index_group(heading, items) |
| 150 | + div do |
| 151 | + h3(class: "text-xs font-semibold uppercase tracking-wide text-base-content/40") { heading } |
| 152 | + ul(class: "mt-3 flex flex-col gap-2") do |
| 153 | + items.each { |item| li { a(href: item.href, class: "link link-hover text-sm") { item.label } } } |
| 154 | + end |
| 155 | + end |
| 156 | + end |
| 157 | + |
| 158 | + # Collapse nav_groups ({ heading => { subgroup => [item] } }) to |
| 159 | + # { heading => [item, ...] } — the landing shows one flat column per heading. |
| 160 | + def flattened_nav |
| 161 | + config.nav_groups.each_with_object({}) do |(heading, grouped), acc| |
| 162 | + items = Array(grouped).flat_map { |_subgroup, list| Array(list) } |
| 163 | + acc[heading] = items unless items.empty? |
| 164 | + end |
| 165 | + end |
| 166 | + end |
| 167 | +end |
0 commit comments