From b4547679e2378223a4274e5d0d182a17f3f99f1b Mon Sep 17 00:00:00 2001 From: Yessiest Date: Thu, 3 Apr 2025 22:16:37 +0000 Subject: [PATCH] fixed style overriding and added wiki pages for each renderer's options --- lib/mmmd/renderers/html.rb | 9 +-- lib/mmmd/renderers/plainterm.rb | 6 +- wiki/renderers/HTML.md | 82 ++++++++++++++++++++ wiki/renderers/Plainterm.md | 131 ++++++++++++++++++++++++++++++++ 4 files changed, 222 insertions(+), 6 deletions(-) create mode 100644 wiki/renderers/HTML.md create mode 100644 wiki/renderers/Plainterm.md diff --git a/lib/mmmd/renderers/html.rb b/lib/mmmd/renderers/html.rb index 72d98c5..45f4ab9 100644 --- a/lib/mmmd/renderers/html.rb +++ b/lib/mmmd/renderers/html.rb @@ -128,11 +128,10 @@ module MMMD def initialize(overrides) @mapping = self.class.mapping - if overrides["mapping"] - overrides["mapping"].each do |key, value| - next unless @mapping[key] - @mapping[key] = @mapping[key].merge(value) - end + overrides["mapping"]&.each do |key, value| + next unless @mapping[key] + + @mapping[key] = @mapping[key].merge(value) end end diff --git a/lib/mmmd/renderers/plainterm.rb b/lib/mmmd/renderers/plainterm.rb index 95279a8..5e36a21 100644 --- a/lib/mmmd/renderers/plainterm.rb +++ b/lib/mmmd/renderers/plainterm.rb @@ -381,7 +381,11 @@ module MMMD def initialize(overrides) @style = self.class.style @effect_priority = self.class.effect_priority - @style = @style.merge(overrides["style"]) if overrides["style"] + overrides["style"]&.each do |key, value| + next unless @style[key] + + @style[key] = @style[key].merge(value) + end end attr_reader :style, :effect_priority diff --git a/wiki/renderers/HTML.md b/wiki/renderers/HTML.md new file mode 100644 index 0000000..9751ce8 --- /dev/null +++ b/wiki/renderers/HTML.md @@ -0,0 +1,82 @@ +HTML renderer +============= + +HTML renderer does exactly what it says on the tin - renders markdown to HTML. +It offers the ability to modify the way output is generated, as well as tags +which are used for every block. + +Global options +-------------- + +Global options are applied to the root of the configuration hash for the +renderer. They can be applied using the following pattern via command +line: + +``` +$ mmmdpp -o '"nameOfGlobalOption": ' ... + +# i.e. +$ mmmdpp -o '"linewrap": 65' ... +``` + +Following global options can be provided: + +- `linewrap` - line wrapping, in number of text columns (80 by default) +- `init_level` - initial indent level of generated text (2 by default) +- `indent` - number of spaces per indent (2 by default) +- `nowrap` - do not output wrapping code, only direct translations of + markdown elements (false by default) +- `head` - array of head elements to add to the default template + output ([] by default) +- `preambule` - text contents to embed before the translation output + (part of template containing head element by default) +- `postambule` - text contents to embed after the translation output + (part of template by default) + +Per-class overrides +------------------- + +Applying a per-class override via command line options works like this: +``` +# see the following paragraph for all known block classes +$ mmmdpp -o '"mapping"."Block::ClassName".override: ' ... + +# i.e. +$ mmmdpp -o '"mapping"."PointBlank::DOM::Paragraph".inline: true' ... +``` + +For library usage, these options roughly translate to the following hash, passed +as the second argument to object initializer: +``` +{ + "mapping" => { + "PointBlank::DOM::Paragraph" => { + inline: true + } + } +} +``` + +Following options can be applied to every class element: + +- `tag` - name of the tag this class should be mapped to. (i.e. + 'PointBlank::DOM::Paragraph' => 'p', 'PointBlank::DOM::InlineEmphasis' => + 'em') +- `sanitize` - sanitize entities in text. shouldn't really be used anywhere + outside of text +- `inline` - the tag should be considered self-closing +- `codeblock` - special case. disables wordwrap, makes the block uninlined + regardless of containing tags. +- `figcaption` - wrap tag into a `
` tag. text contained in the tag is + copied into a caption. +- `outer` - hash of parameters for an outer wrapping tag. can be defined + recursively. all options in this list apply. +- `href` - add a href attribute. works only on links and classes containing + a `:uri` attribute +- `title` - add a title attribute. works only on classes that have a + `:title` attribute +- `style` - define an inline CSS style to embed into the tag. +- `src` - add an src attribute. works only on images and classes containing + a `:uri` attribute +- `alt` - add an alt attribute. works only on classes that have a + `:title` attribute diff --git a/wiki/renderers/Plainterm.md b/wiki/renderers/Plainterm.md new file mode 100644 index 0000000..bd0b760 --- /dev/null +++ b/wiki/renderers/Plainterm.md @@ -0,0 +1,131 @@ +Plainterm renderer +================== + +Plainterm renderer renders markdown documents into a prettier format for reading +in the terminal. It uses certain control codes to make it work. Styles applied +to various elements can be changed. + +Applicable global options +------------------------- + +Global options are applied to the root of the configuration hash for the +renderer. They can be applied using the following pattern via command +line: + +``` +$ mmmdpp -o '"nameOfGlobalOption": ' ... + +# i.e. +$ mmmdpp -o '"hsize": 65' ... +``` + +- `style` - override the style of certain elements. See "Style overrides" +- `hsize` - horizontal size to align the contents to. Automatically + set to the width of the current terminal by default, or, if unavailable, + to 80 columns. + +Style overrides +--------------- + +Style overrides provide per-class overrides for element style. It's essentially +a stylesheet applied to the element. + +Applying a style override via command line options works like this: +``` +# see the following paragraph for all known block classes +$ mmmdpp -o '"style"."Block::ClassName".override: ' ... + +# i.e. +$ mmmdpp -o '"style"."PointBlank::DOM::Paragraph".indent: false' ... +``` + +For library usage, these options roughly translate to the following hash, passed +as the second argument to object initializer: +``` +{ + "style" => { + "PointBlank::DOM::Paragraph" => { + indent: false + } + } +} +``` + +Applicable style overrides: +- `indent` (boolean) - increase indentation +- `increase_level` (boolean) - decrease horizontal space occupied (needed with + indent) +- `center` (boolean) - center text +- `bold` (boolean) - render text in bold +- `italics` (boolean) - render text in italics +- `strikethrough` (boolean) - render text with strikethrough +- `bg` (text, #RGB) - set color background +- `fg` (text, #RGB) - set color foreground +- `box` (boolean) - render contents in an ascii box +- `rjust` (boolean) - right-justify text +- `extra_newlines` (boolean) - add extra newlines around the text block +- `underline_block` (boolean) - underline text block, from left visual boundary + of text to right visual boundary of text +- `underline_full_block` (boolean) - underline text block, from left border to + right border +- `bullet` (boolean) - add bullet to block, used for bullet lists +- `numbered` (boolean) - add numbered point to block, used for ordered lists +- `leftline` (boolean) - draw a line on the left side of the block, top to + bottom + +Style defaults +-------------- + +These are the defaults applied to each class of text block + +- `PointBlank::DOM::Paragraph`: + - `indent` + - `increase_level` +- `PointBlank::DOM::Text`: + - none applied by default +- `PointBlank::DOM::SetextHeading1` (underline style of heading in markdown, + level 1) + - `center` + - `bold` + - `extra_newlines` + - `underline_full_block` +- `PointBlank::DOM::SetextHeading2` (underline style of heading in markdown, + level 2) + - `center` + - `underline_block` +- `PointBlank::DOM::ATXHeading1` (hash-symbol prefix style of heading, + level 1) + - (same as SetextHeading1) +- `PointBlank::DOM::ATXHeading2` (hash-symbol heading, level 2) + - (same as SetextHeading2) +- `PointBlank::DOM::ATXHeading3` (hash-symbol heading, level 3) + - `underline` + - `bold` +- `PointBlank::DOM::ATXHeading4` (hash-symbol heading, level 4) + - `bold` + - `underline` +- `PointBlank::DOM::ATXHeading5` (hash-symbol heading, level 5) + - `underline` +- `PointBlank::DOM::ATXHeading6` (hash-symbol heading, level 6) + - `underline` +- `PointBlank::DOM::InlineImage` (image link) + - `underline` +- `PointBlank::DOM::InlineLink` (link) + - `underline` +- `PointBlank::DOM::InlinePre` (inline code) + - none by default +- `PointBlank::DOM::InlineEmphasis` + - `italics` +- `PointBlank::DOM::InlineStrong` (strong emphasis) + - `bold` +- `PointBlank::DOM::ULListElement` (element of an unordered list) + - `bullet` + - `increase_level` +- `PointBlank::DOM::OLListElement` (element of an ordered list) + - `numbered` + - `increase_level` +- `PointBlank::DOM::QuoteBlock` + - `leftline` + - `increase_level` +- `PointBlank::DOM::HorizontalRule` + - `hrule`