Skip to content

selvinortiz/craft.doxter

Repository files navigation

Doxter

Doxter

Lovingly crafted by Selvin Ortiz for Craft CMS

Doxter is a markdown plugin designed to improve the way you write documentation

For the Craft 3 version of this plugin, see craft-plugin-doxter.

Support Craft Plugin Development By Selvin Ortiz

Installation

  1. Download the latest release or clone this repo
  2. Extract the archive and place doxter inside your craft/plugins directory
  3. Install Doxter from the Control Panel @ Settings > Plugins
  4. Adjust plugin settings from the Control Panel @ Settings > Plugins > Doxter
  5. FieldType settings can be adjusted when you create your Doxter field

Features

  • Live Preview Support
  • Fast and consistent Github Flavored Markdown Parsing
  • Linkable Headers based on parsing settings
  • Advanced Reference Tags parsing
  • Minimalist editor with custom toolbar for Reference Tags
  • Extensible Shortcode parsing support
  • Event driven parsing API for developers
  • Advanced fenced codeblock parsing
  • Support for typography styles for better web typography
  • Support for multiple fieldtypes in single Entry Type or Matrix Field
  • Unit Tested with care

Doxter Field

Doxter is a field type that allows you to write and parse markdown content.

Workflow

  1. Create a new Doxter field
  2. Add the new field to a field layout in your entry type
  3. Write your markdown and save it along with your entry

The content will be saved as plain text and returned as a DoxterModel

Doxter Model

text()

Returns the plain text content stored via the field type

{{ entry.doxterField.text() }}

It is also worth noting that this is the default behavior when you use you the Doxter in string context.

{# __toString() returns the text() equivalent #}
{{ entry.doxterField }}

html()

Returns properly formatted HTML parsed from the the plain text content stored via the Doxter field type.

{{ entry.doxterField.html() }}

Calling html() without any params will use the default parsing option defined in your settings. Passing an options object html({}) gives you full control on a per field basis.

Doxter Filter

The doxter filter is still supported and can be used to parse markdown from any source.

{{ "Doxter _markdown_"|doxter }}
{# or #}
{{ "Doxter _markdown_"|doxter({}) }}

Options

The Doxter Model html() method and the Doxter Filter accept an array of options to override your defaults.

Option Type Default Description
codeBlockSnippet string see snippet below
addHeaderAnchors boolean true Whether to parse headers and add anchors for direct linking
addHeaderAnchorsTo array [h1, h2, h3] Which headers to add anchors to if header parsing is enabled
addTypographyStyles bool false Whether typography styles should be applied
startingHeaderLevel string h1 Which tag should be use for the initial header discussed on issue #13
parseReferenceTags boolean true Whether reference tags should be parsed
parseShortcodes boolean true Whether Doxter supported shortcodes should be parsed

Default Code Block Snippet

The code block snippet allows you to define how fenced code blocks should be rendered by providing two variables you can use in your snippet.

<!-- Default snippet targets RainbowJS -->
<pre><code data-language="language-{languageClass}">{sourceCode}</code></pre>
Variable Description Example
languageClass The programming/scripting language added in the fenced code block js, php
sourceCode The actual code inside the fenced code block echo "Code";

Changes

All noteworthy changes can be found in CHANGELOG.md

Feedback

If you have any feedback, questions, or concerns, please reach out to me on twitter @selvinortiz

Credits

Doxter was lovingly crafted by Selvin Ortiz with the help of these third party libraries.

  1. Parsedown for lightening fast and consistent markdown parsing
  2. Parsedown Extra for lightening fast and consistent markdown

Special thanks to their developer and maintainers!

License

Doxter is open source software licensed under the MIT license

Open Source Initiative