Class: DocsKit::MarkdownExport

Inherits:
Object
  • Object
show all
Defined in:
lib/docs_kit/markdown_export.rb,
lib/docs_kit/markdown_export/table.rb,
lib/docs_kit/markdown_export/blocks.rb,
lib/docs_kit/markdown_export/inline.rb

Overview

Derives a faithful GFM Markdown twin of a docs page FROM the page's own rendered HTML. The gem emits the HTML, so the tag vocabulary is bounded and a small hand-rolled Nokogiri visitor converts it exactly — no dependence on authoring style (Phlex, md islands, and raw tags in Prose all convert identically because conversion happens post-render).

DocsKit::MarkdownExport.new(page_view, view_context:, base_url: req.base_url).to_md

The page is rendered, the #docs-content region (DocsUI::Shell's anchor) is extracted, [data-md-skip] chrome is stripped, and the remaining subtree is walked to Markdown. Data hints the kit stamps at render time drive the tricky cases: data-md-lang (DocsUI::Code) → a ```lang fence; data-md-callout (DocsUI::Callout) → a > **Tip:** blockquote.

Defined Under Namespace

Classes: Blocks, Inline, Table

Constant Summary collapse

CONTENT_SELECTOR =

The extraction anchor DocsUI::Shell stamps on its content column.

"#docs-content"
DROP_SELECTOR =

Elements dropped whole — chrome and non-content that must never reach the Markdown twin. [data-md-skip] is authored (Page's "← Home" nav); script and style carry no readable content.

"[data-md-skip], script, style"
CALLOUT_LABELS =

Callout level → the bold label opening its blockquote.

{ "note" => "Note", "tip" => "Tip", "warning" => "Warning" }.freeze
KEYWORD_PARAM_TYPES =

The parameter kinds that count as a keyword arg (required or optional) when sniffing whether a view's #call accepts a view_context: kwarg.

%i[key keyreq].freeze

Instance Method Summary collapse

Constructor Details

#initialize(view, view_context: nil, base_url: nil) ⇒ MarkdownExport

view: a renderable page (a Phlex component in production). view_context: the Rails view context to render it through (CSRF, url helpers). base_url: the request's base URL, used to absolutize relative link/image hrefs so the exported Markdown is portable.



39
40
41
42
43
 
# File 'lib/docs_kit/markdown_export.rb', line 39

def initialize(view, view_context: nil, base_url: nil)
  @view = view
  @view_context = view_context
  @base_url = base_url
end

Instance Method Details

#absolutize(url) ⇒ Object

Absolutize a relative href/src against the base URL; leave absolute and anchor/mailto links untouched. No base URL → return as-is.



57
58
59
60
61
62
63
 
# File 'lib/docs_kit/markdown_export.rb', line 57

def absolutize(url)
  return url if url.nil? || url.empty?
  return url unless @base_url
  return url if url.match?(%r{\A(?:[a-z][a-z0-9+.-]*:|//|#)}i)

  "#{@base_url.chomp('/')}/#{url.delete_prefix('/')}"
end

#to_md ⇒ Object

The page's content as GFM Markdown, or "" when there is no #docs-content region (a page that isn't the docs chrome — the HTML route is untouched).



47
48
49
50
51
52
53
 
# File 'lib/docs_kit/markdown_export.rb', line 47

def to_md
  content = extract_content
  return "" unless content

  content.search(DROP_SELECTOR).each(&:remove)
  Blocks.new(self).render(content).strip
end