From 4491fa41d6d45648ccbf4bc88cedcff666ec91ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20H=C3=B8egh?= <22152591+BenjaminHoegh@users.noreply.github.com> Date: Mon, 26 Aug 2024 22:20:22 +0200 Subject: [PATCH] 1.3.x docs --- package.json | 12 +-- .../Configuration/Abbreviations.md | 77 ++++++++++++++++++ .../version-1.3.x/Configuration/Code.md | 57 +++++++++++++ .../version-1.3.x/Configuration/Comments.md | 51 ++++++++++++ .../Configuration/Definition Lists.md | 43 ++++++++++ .../version-1.3.x/Configuration/Diagrams.md | 68 ++++++++++++++++ .../version-1.3.x/Configuration/Emojis.md | 61 ++++++++++++++ .../version-1.3.x/Configuration/Emphasis.md | 71 +++++++++++++++++ .../version-1.3.x/Configuration/Footnotes.md | 51 ++++++++++++ .../version-1.3.x/Configuration/Headings.md | 79 +++++++++++++++++++ .../version-1.3.x/Configuration/Images.md | 51 ++++++++++++ .../version-1.3.x/Configuration/Links.md | 45 +++++++++++ .../version-1.3.x/Configuration/Lists.md | 59 ++++++++++++++ .../version-1.3.x/Configuration/Math.md | 72 +++++++++++++++++ .../version-1.3.x/Configuration/Quotes.md | 31 ++++++++ .../Configuration/Smartypants.md | 65 +++++++++++++++ .../Configuration/Table of Contents.md | 70 ++++++++++++++++ .../version-1.3.x/Configuration/Tables.md | 64 +++++++++++++++ .../Configuration/Thematic Breaks.md | 39 +++++++++ .../Configuration/Typographer.md | 46 +++++++++++ versioned_docs/version-1.3.x/Installation.md | 51 ++++++++++++ versioned_docs/version-1.3.x/Introduction.md | 29 +++++++ .../version-1.3.x-sidebars.json | 8 ++ versions.json | 1 + 24 files changed, 1195 insertions(+), 6 deletions(-) create mode 100644 versioned_docs/version-1.3.x/Configuration/Abbreviations.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Code.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Comments.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Definition Lists.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Diagrams.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Emojis.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Emphasis.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Footnotes.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Headings.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Images.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Links.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Lists.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Math.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Quotes.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Smartypants.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Table of Contents.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Tables.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Thematic Breaks.md create mode 100644 versioned_docs/version-1.3.x/Configuration/Typographer.md create mode 100644 versioned_docs/version-1.3.x/Installation.md create mode 100644 versioned_docs/version-1.3.x/Introduction.md create mode 100644 versioned_sidebars/version-1.3.x-sidebars.json diff --git a/package.json b/package.json index faf7ec7..f90bcd9 100644 --- a/package.json +++ b/package.json @@ -15,9 +15,9 @@ "typecheck": "tsc" }, "dependencies": { - "@docusaurus/core": "^3.5.0", - "@docusaurus/preset-classic": "^3.5.0", - "@docusaurus/theme-mermaid": "^3.5.0", + "@docusaurus/core": "^3.5.2", + "@docusaurus/preset-classic": "^3.5.2", + "@docusaurus/theme-mermaid": "^3.5.2", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "prism-react-renderer": "^2.3.0", @@ -27,9 +27,9 @@ "remark-math": "^6.0.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "^3.5.0", - "@docusaurus/tsconfig": "^3.5.0", - "@docusaurus/types": "^3.5.0", + "@docusaurus/module-type-aliases": "^3.5.2", + "@docusaurus/tsconfig": "^3.5.2", + "@docusaurus/types": "^3.5.2", "typescript": "~5.2.2" }, "browserslist": { diff --git a/versioned_docs/version-1.3.x/Configuration/Abbreviations.md b/versioned_docs/version-1.3.x/Configuration/Abbreviations.md new file mode 100644 index 0000000..15a7067 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Abbreviations.md @@ -0,0 +1,77 @@ +--- +title: Abbreviations +--- + +# Abbreviations + +## Description + +The Abbreviations feature provides automatic detection and formatting of abbreviations within your Markdown content. By wrapping abbreviations in `` tags, it enhances text comprehension and accessibility, allowing users to see the full meaning of abbreviations on hover. + +## Configuration Syntax + +To configure the Abbreviations feature, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for the Abbreviations feature: + +```php +$configValue = config()->get('abbreviations'); +``` + +### Setting the Configuration + +To adjust the Abbreviations feature, use: + +```php +config()->set('abbreviations', (bool|array) $value); +``` + +- `$value` can be a boolean to enable or disable the feature globally, or an array for more detailed configuration options. + +## Configuration Options + +The Abbreviations feature supports the following settings: + +- **allow_custom** (bool): Allows the definition of custom abbreviations directly within your Markdown content. This option is enabled by default. +- **predefined** (array): Provides a list of predefined abbreviations and their full meanings to ensure consistency across your documents. + +## Examples + +### Disable Abbreviations + +To completely disable the processing of abbreviations: + +```php +$ParsedownExtended->config()->set('abbreviations', false); +``` + +### Predefine Abbreviations + +To set up a predefined list of abbreviations: + +```php +$ParsedownExtended->config()->set('abbreviations', [ + 'predefined' => [ + 'CSS' => 'Cascading Style Sheets', + 'HTML' => 'HyperText Markup Language', + 'JS' => 'JavaScript', + ], +]); +``` + +### Use Predefined Abbreviations Only + +To restrict usage to only predefined abbreviations and disable custom abbreviations: + +```php +$ParsedownExtended->config()->set('abbreviations', [ + 'allow_custom' => false, + 'predefined' => [ + 'CSS' => 'Cascading Style Sheets', + 'HTML' => 'HyperText Markup Language', + 'JS' => 'JavaScript', + ], +]); +``` \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Code.md b/versioned_docs/version-1.3.x/Configuration/Code.md new file mode 100644 index 0000000..a918f70 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Code.md @@ -0,0 +1,57 @@ +--- +title: Code +--- + +# Code + +## Description + +Code snippets within Markdown documents can be presented in two distinct styles: inline and block. Inline code is used for highlighting code or commands within a sentence, whereas block code is suited for larger code excerpts or examples that should stand apart from the main text. ParsedownExtended enhances the management of both inline and block code snippets, offering configurable settings to fine-tune their processing and presentation. + +## Configuration Syntax + +To configure the code processing settings, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for code processing: + +```php +$configValue = $ParsedownExtended->config()->get('code'); +``` + +### Setting the Configuration + +To adjust the code processing settings: + +```php +$ParsedownExtended->config()->set('code', (bool|array) $value); +``` + +- `$value` is a boolean indicating whether inline code processing is enabled (`true`) or disabled (`false`). Alternatively, you can use an array for more detailed configuration options. By default, inline code formatting is usually enabled. + +## Examples + +### Disabling All Code Processing + +To disable the processing of all code, including both inline and block code: + +```php +$ParsedownExtended->config()->set('code', false); +``` + +### Disabling Inline Code + +To disable the formatting of inline code, preventing text surrounded by backticks from being rendered distinctly: + +```php +$ParsedownExtended->config()->set('code.inline', false); +``` + +### Disabling Block Code + +To disable the processing of block code, which is usually delimited by triple backticks or indentation: + +```php +$ParsedownExtended->config()->set('code.block', false); +``` \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Comments.md b/versioned_docs/version-1.3.x/Configuration/Comments.md new file mode 100644 index 0000000..5ff7bc2 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Comments.md @@ -0,0 +1,51 @@ +--- +title: Comments +--- + +# Comments + +## Description + +The Comments feature in Markdown allows you to include notes or annotations within your content that won't be rendered in the final output. This is useful for adding explanations or reminders that are visible in the source but invisible to the end user. ParsedownExtended provides options to enable or disable the processing of comments within your Markdown files. + +## Configuration Syntax + +To configure the Comments feature, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for comment processing: + +```php +$configValue = $ParsedownExtended->config()->get('comments'); +``` + +### Setting the Configuration + +To adjust the Comments feature: + +```php +$ParsedownExtended->config()->set('comments', (bool) $value); +``` + +- `$value` is a boolean indicating whether comment processing is enabled (`true`) or disabled (`false`). By default, comment processing may be enabled or disabled based on your system's settings. + +## Examples + +### Disabling Comments + +To disable the processing of comments in Markdown, preventing any comments from being included in the source: + +```php +$ParsedownExtended->config()->set('comments', false); +``` + +### Enabling Comments + +To enable the processing of comments, allowing annotations to be included in your Markdown files but not rendered in the final output: + +```php +$ParsedownExtended->config()->set('comments', true); +``` + +This configuration will ensure that any comments added within the Markdown using the appropriate syntax will be processed accordingly, following your specified settings. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Definition Lists.md b/versioned_docs/version-1.3.x/Configuration/Definition Lists.md new file mode 100644 index 0000000..e9ad5d5 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Definition Lists.md @@ -0,0 +1,43 @@ +--- +title: Definition Lists +--- + +# Definition Lists + +## Description + +Definition lists allow for the organization of terms and their corresponding definitions in a structured format. This functionality enables authors to create glossaries or specify key concepts with descriptions directly within their Markdown content. While the capability to interpret definition list syntax comes from Parsedown, ParsedownExtended provides enhanced support by allowing users to easily enable or disable this feature through its configuration settings. + +## Configuration Syntax + +To configure the processing of definition lists in your Markdown, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for definition list processing: + +```php +$configValue = $ParsedownExtended->config()->get('definition_lists'); +``` + +### Setting the Configuration + +To adjust the processing of definition lists: + +```php +$ParsedownExtended->config()->set('definition_lists', (bool) $value); +``` + +- `$value` is a boolean indicating whether definition lists should be processed (`true`) or ignored (`false`). + +## Examples + +### Disable Definition Lists + +To prevent the automatic processing of definition lists, thereby disabling the feature: + +```php +$ParsedownExtended->config()->set('definition_lists', false); +``` + +This configuration allows you to control whether definition lists are recognized and formatted within your Markdown content based on your specific needs. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Diagrams.md b/versioned_docs/version-1.3.x/Configuration/Diagrams.md new file mode 100644 index 0000000..ba24c20 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Diagrams.md @@ -0,0 +1,68 @@ +--- +title: Diagrams +--- + +# Diagrams + +## Description + +ParsedownExtended introduces support for incorporating diagrams directly into Markdown documents, enhancing visual representation and understanding. This feature recognizes syntax intended for diagram rendering, specifically designed to work with [ChartJS](https://www.chartjs.org) and [Mermaid](https://mermaid-js.github.io/mermaid/). ParsedownExtended ensures that diagram code is preserved and remains unaltered for client-side rendering, requiring the inclusion of ChartJS and Mermaid JavaScript libraries in your project. + +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` + +## Configuration Syntax + +To enable the diagrams feature in ParsedownExtended, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for diagram support: + +```php +$configValue = $ParsedownExtended->config()->get('diagrams'); +``` + +### Setting the Configuration + +To adjust the diagram processing settings: + +```php +$ParsedownExtended->config()->set('diagrams', (bool|array) $value); +``` + +- `$value` can be a boolean to enable or disable diagram support globally, or an array for more specific configuration options. + +## Configuration Options + +This feature allows the following settings: + +- **chartjs**: Enable or disable support for ChartJS diagrams. +- **mermaid**: Enable or disable support for Mermaid diagrams. + +## Examples + +### Enable Diagrams + +To activate diagram support, ensuring that Markdown containing ChartJS or Mermaid syntax is properly recognized and left intact for client-side rendering: + +```php +$ParsedownExtended->config()->set('diagrams', true); +``` + +### Disable a Specific Diagram Type + +To disable support for a specific diagram type, such as ChartJS: + +```php +$ParsedownExtended->config()->set('diagrams', [ + 'chartjs' => false +]); +``` + +This configuration allows you to control how diagram syntax is handled within your Markdown content, ensuring that it is processed according to your project’s requirements. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Emojis.md b/versioned_docs/version-1.3.x/Configuration/Emojis.md new file mode 100644 index 0000000..5a1ef8a --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Emojis.md @@ -0,0 +1,61 @@ +--- +title: Emojis +--- + +# Emojis + +## Description + +ParsedownExtended enriches Markdown documents with the capability to insert emojis using shortcodes, a feature that enhances readability and emotional expression within text. Shortcodes, which are emoji names enclosed in colons (e.g., `:smile:`), are automatically converted into their corresponding emoji characters, allowing for a more engaging and visually appealing document. + +## Configuration Syntax + +To enable or disable emoji shortcodes in ParsedownExtended, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for emoji shortcodes: + +```php +$configValue = $ParsedownExtended->config()->get('emojis'); +``` + +### Setting the Configuration + +To adjust the emoji shortcode processing: + +```php +$ParsedownExtended->config()->set('emojis', (bool) $value); +``` + +- `$value` is a boolean indicating whether emoji shortcodes should be processed (`true`) or not (`false`). + +## Examples + +### Enable Emoji Shortcodes + +To enable the interpretation and conversion of emoji shortcodes into actual emojis: + +```php +$ParsedownExtended->config()->set('emojis', true); +``` + +### Usage Example + +Incorporate emojis into your Markdown by using shortcodes: + +**Markdown Input:** + +```markdown +Gone camping! :tent: Be back soon. + +That is so funny! :joy: +``` + +**Rendered Output:** + +Gone camping! ⛺ Be back soon. + +That is so funny! 😂 + +This setup allows you to easily control whether emojis are converted from shortcodes within your Markdown content, helping you create more expressive and visually appealing documents. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Emphasis.md b/versioned_docs/version-1.3.x/Configuration/Emphasis.md new file mode 100644 index 0000000..fd8d078 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Emphasis.md @@ -0,0 +1,71 @@ +--- +title: Emphasis +--- + +# Emphasis + +## Description + +Emphasis in Markdown is essential for highlighting text through italicization, boldening, or other emphasis methods. ParsedownExtended enhances your control over these emphasis styles, allowing for detailed customization or complete disabling of emphasis features to suit your document's needs. + +## Available Emphasis Styles + +ParsedownExtended supports a range of emphasis styles, which can be individually enabled or disabled: + +- **bold:** Applies bold formatting. +- **italic:** Applies italic formatting. +- **mark:** Applies highlighting using the `` tag. +- **strikethroughs:** Applies strikethrough formatting. +- **insertions:** Applies underline formatting typically used to indicate insertions. +- **subscript:** Applies subscript formatting. +- **superscript:** Applies superscript formatting. +- **keystrokes:** Applies formatting for keystrokes. + +## Configuration Syntax + +Configure emphasis features in ParsedownExtended using `config()->set()` and `config()->get()`. You can enable or disable specific emphasis styles or turn off all emphasis processing: + +### Getting the Current Configuration + +To retrieve the current configuration for emphasis styles: + +```php +$configValue = $ParsedownExtended->config()->get('emphasis'); +``` + +### Setting the Configuration + +To configure specific emphasis styles: + +```php +$ParsedownExtended->config()->set('emphasis', [ + 'bold' => true, // Enable bold emphasis + 'italic' => true, // Enable italic emphasis + // Specify other emphasis styles as needed +]); +``` + +This flexibility allows you to tailor the rendering of your Markdown content precisely. + +## Examples + +### Enable Specific Emphasis Styles + +Enable only bold and marked text, while disabling others: + +```php +$ParsedownExtended->config()->set('emphasis', [ + 'bold' => true, + 'mark' => true, +]); +``` + +### Disable All Emphasis + +To completely disable all forms of text emphasis: + +```php +$ParsedownExtended->config()->set('emphasis', false); +``` + +This configuration allows you to have full control over how text emphasis is handled within your Markdown documents, ensuring that the content aligns with your specific presentation needs. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Footnotes.md b/versioned_docs/version-1.3.x/Configuration/Footnotes.md new file mode 100644 index 0000000..80e606e --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Footnotes.md @@ -0,0 +1,51 @@ +--- +title: Footnotes +--- + +# Footnotes + +## Description + +Footnotes in Markdown are an elegant solution for adding notes, citations, or additional information without overcrowding the main text. ParsedownExtended supports footnotes, allowing you to insert a superscript number linked to the footnote content at the bottom of the page. This feature enhances document readability, enabling readers to easily access related notes and references. + +## Configuration Syntax + +To manage footnotes in your documents using ParsedownExtended, utilize the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for footnotes: + +```php +$configValue = $ParsedownExtended->config()->get('footnotes'); +``` + +### Setting the Configuration + +To activate or deactivate the footnotes feature: + +```php +$ParsedownExtended->config()->set('footnotes', (bool) $value); +``` + +This setting allows you to enable or disable footnotes based on your documentation needs. + +## Examples + +### Enable Footnotes + +Footnotes are enabled by default. To explicitly ensure they are enabled: + +```php +$ParsedownExtended->config()->set('footnotes', true); +``` + +### Disable Footnotes + +To disable footnotes, preventing the parsing and rendering of footnote syntax: + +```php +$ParsedownExtended->config()->set('footnotes', false); +``` + +By configuring the footnotes feature, you can tailor how your Markdown content utilizes footnotes, providing a cleaner and more informative reading experience. Whether enabling detailed references or maintaining a streamlined document body, ParsedownExtended offers the flexibility to suit your formatting preferences. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Headings.md b/versioned_docs/version-1.3.x/Configuration/Headings.md new file mode 100644 index 0000000..68992a7 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Headings.md @@ -0,0 +1,79 @@ +--- +title: Headings +--- + +# Headings + +## Description + +Markdown headings, marked by hash characters (`#`), indicate different levels of content hierarchy from `h1` to `h6`. ParsedownExtended not only supports these standard headings but also offers enhanced functionalities such as automatic permalink generation and customizable heading levels. A key feature is the ability for users to define their own logic for creating anchor IDs using the `setCreateAnchorIDCallback` method. + +## Configuration Syntax + +To configure headings in ParsedownExtended, use the `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for headings: + +```php +$configValue = $ParsedownExtended->config()->get('headings'); +``` + +### Setting the Configuration + +To configure the headings feature: + +```php +$ParsedownExtended->config()->set('headings', (bool|array) $value); +``` + +This setting can be a boolean to globally enable or disable headings, or an array for more detailed configurations. + +## Configuration Options + +- **allowed_levels** (array): Specify which heading levels are allowed. +- **auto_anchors** (boolean): Toggle automatic permalink generation for headings. + - **blacklist** (array): List of IDs to exclude from automatic anchor generation. + - **delimiter** (string): Character(s) to use for separating words in anchor IDs. + - **lowercase** (boolean): Whether to convert anchor IDs to lowercase. + - **transliterate** (boolean): Whether to transliterate characters in anchor IDs. + - **replacements** (array): List of characters to replace in anchor IDs. + +## Examples + +### Disable Headings + +To disable headings processing: + +```php +$ParsedownExtended->config()->set('headings', false); +``` + +### Custom Anchor IDs + +Implement custom logic for anchor IDs: + +```php +$ParsedownExtended->config()->set('headings.custom_anchor_id_callback', function($text, $level) { + return 'custom-anchor-' . $level . '-' . strtolower(str_replace(' ', '-', $text)); +}); +``` + +### Configure Allowed Headings + +Specify allowed heading levels: + +```php +$ParsedownExtended->config()->set('headings.allowed_levels', ['h1', 'h2', 'h3']); +``` + +### Blacklist Heading IDs + +Define a blacklist for heading IDs: + +```php +$ParsedownExtended->config()->set('headings.auto_anchors.blacklist', ['my_blacklisted_header_id', 'another_blacklisted_id']); +``` + +This configuration gives you complete control over how headings are processed and rendered in your Markdown documents, allowing you to tailor the content hierarchy and linking behavior to your specific needs. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Images.md b/versioned_docs/version-1.3.x/Configuration/Images.md new file mode 100644 index 0000000..f1e0eb8 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Images.md @@ -0,0 +1,51 @@ +--- +title: Images +--- + +# Images + +## Description + +Incorporating images into Markdown greatly enhances the visual impact and effectiveness of your content. ParsedownExtended supports the standard Markdown syntax for embedding images, making it simple to include visuals in your documents. With this feature, you can easily add images using a syntax similar to Markdown links, enabling a more engaging and illustrative content presentation. + +## Configuration Syntax + +Control the processing of images in Markdown using ParsedownExtended's `config()->set()` and `config()->get()` methods: + +### Getting the Current Configuration + +To retrieve the current configuration for image processing: + +```php +$configValue = config()->get('images'); +``` + +### Setting the Configuration + +To enable or disable the rendering of images in your Markdown content: + +```php +config()->set('images', (bool) $value); +``` + +This setting allows you to enable (`true`) or disable (`false`) the rendering of images in your Markdown content. + +## Examples + +### Enable Images + +Images are enabled by default. To explicitly ensure they are enabled: + +```php +$ParsedownExtended->config()->set('images', true); +``` + +### Disable Images + +To prevent Markdown syntax from being processed as images, effectively disabling image rendering: + +```php +$ParsedownExtended->config()->set('images', false); +``` + +This configuration provides you with the flexibility to control whether images are included in your Markdown documents, ensuring that your content is presented exactly as you intend. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Links.md b/versioned_docs/version-1.3.x/Configuration/Links.md new file mode 100644 index 0000000..656c475 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Links.md @@ -0,0 +1,45 @@ +--- +title: Links +--- + +# Links + +## Description + +In Markdown, links are crucial for directing readers to additional resources or related content. ParsedownExtended enhances link functionality in Markdown, offering options to customize how links are processed, including the handling of email addresses as mailto links. This feature allows for greater control over link creation and presentation in your documents. + +## Configuration Syntax + +Configure link processing in ParsedownExtended using the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('links', (bool|array) $value); +``` + +This setting can be a simple boolean to enable or disable all link processing, or an array for more granular control over specific types of links. + +## Parameters + +- **email_links** (boolean): Determines whether email addresses are automatically converted into mailto links. This is enabled by default. + +## Examples + +### Disable All Link Processing + +To disable the processing and rendering of all links: + +```php +$ParsedownExtended->config()->set('links', false); +``` + +### Disable Mailto Links + +To disable the automatic conversion of email addresses into mailto links: + +```php +$ParsedownExtended->config()->set('links', [ + 'email_links' => false +]); +``` + +Using the full syntax like this ensures that users understand how to properly apply the settings within their specific instance of `ParsedownExtended`, reducing confusion and making your documentation more practical and user-friendly. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Lists.md b/versioned_docs/version-1.3.x/Configuration/Lists.md new file mode 100644 index 0000000..1667136 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Lists.md @@ -0,0 +1,59 @@ +--- +title: Lists +--- + +# Lists + +## Description + +Lists in Markdown documents are versatile, allowing for the creation of both ordered and unordered lists, along with specialized task lists. These can be nested to various levels to organize content efficiently. ParsedownExtended enhances the handling of lists by providing configurable options to manage how they are processed, including enabling or disabling them entirely or tweaking the behavior of task lists specifically. + +## Configuration Syntax + +To configure list processing in ParsedownExtended, use the `config()->set()` method with appropriate parameters: + +```php +$ParsedownExtended->config()->set('lists', (bool|array) $value); +``` + +- `$value` can be a boolean to enable (`true`) or disable (`false`) list processing altogether, or an array to configure specific types of lists, such as task lists. + +## Examples + +### Basic List Example + +A simple unordered list in Markdown looks like this: + +```markdown +- First ordered list item. +- Second ordered list item. +- Third ordered list item. +- Fourth ordered list item. +- Fifth ordered list item. +``` + +### Disabling Lists + +To disable list processing: + +```php +$ParsedownExtended->config()->set('lists', false); +``` + +### Task Lists + +Task lists allow for interactive checkboxes in your lists, ideal for to-do lists or checklists: + +```markdown +- [x] Write the press release +- [ ] Update the website +- [ ] Contact the media +``` + +To disable task list processing: + +```php +$ParsedownExtended->config()->set('lists.tasks', false); +``` + +This documentation ensures that users have the correct context and syntax for configuring list processing in their Markdown documents using ParsedownExtended. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Math.md b/versioned_docs/version-1.3.x/Configuration/Math.md new file mode 100644 index 0000000..ae807fe --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Math.md @@ -0,0 +1,72 @@ +--- +title: Math +--- + +# Math + +## Description + +ParsedownExtended introduces support for LaTeX within Markdown, allowing you to incorporate mathematical expressions and notation seamlessly into your documents. By identifying and preserving LaTeX syntax, ParsedownExtended facilitates the use of client-side rendering libraries like [KaTeX](https://katex.org) to render these expressions. This feature is invaluable for academic, scientific, and technical documentation where complex mathematical formulas need to be clearly presented. + +$$ +I = \int_0^{2\pi} \sin(x)\,dx +$$ + +## Configuration Syntax + +To enable LaTeX support in ParsedownExtended, use the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('math', (bool|array) $value); +``` + +This configuration can be set to `true` to enable LaTeX processing, or more detailed options can be specified through an array. + +## Parameters + +The `math` feature allows the following configurations: + +- **enabled** (boolean): Enable or disable LaTeX processing globally. +- **inline** (array): Configure inline math expressions. + - **delimiters** (array): Define the delimiters for inline math expressions. +- **block** (array): Configure block math expressions. + - **delimiters** (array): Define the delimiters for block math expressions. + +> Custom delimiters may not work as expected when using characters not registered in `$specialCharacters`. + +## Examples + +### Enable LaTeX Support + +To activate LaTeX processing, allowing Markdown to include LaTeX expressions for client-side rendering: + +```php +$ParsedownExtended->config()->set('math', true); +``` + +### Configure Inline and Block Math Separately + +To configure inline and block math processing separately: + +```php +$ParsedownExtended->config()->set('math', [ + 'inline' => [ + 'delimiters' => [ + ['left' => '\\(', 'right' => '\\)'], + ], + ], + 'block' => [ + 'delimiters' => [ + ['left' => '$$', 'right' => '$$'], + ['left' => '\\begin{equation}', 'right' => '\\end{equation}'], + ['left' => '\\begin{align}', 'right' => '\\end{align}'], + ['left' => '\\begin{alignat}', 'right' => '\\end{alignat}'], + ['left' => '\\begin{gather}', 'right' => '\\end{gather}'], + ['left' => '\\begin{CD}', 'right' => '\\end{CD}'], + ['left' => '\\[', 'right' => '\\]'], + ], + ], +]); +``` + +This documentation provides users with clear instructions on how to enable and configure LaTeX support for mathematical expressions within their Markdown content using the full context of `$ParsedownExtended->config()->set()`. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Quotes.md b/versioned_docs/version-1.3.x/Configuration/Quotes.md new file mode 100644 index 0000000..1cef70b --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Quotes.md @@ -0,0 +1,31 @@ +--- +title: Quotes +--- + +# Quotes + +## Description + +Blockquotes allow for the inclusion of quoted sections from external sources within your Markdown documents. This capability, provided by the original Parsedown parser, is enhanced in ParsedownExtended by offering configurable settings to manage how blockquotes are processed. By prefixing text with a `>` character, users can create blockquotes, which are then automatically formatted with `
` tags by Parsedown. + +## Configuration Syntax + +Configure the processing of blockquotes using ParsedownExtended's `config()->set()` method: + +```php +$ParsedownExtended->config()->set('quotes', (bool) $value); +``` + +- `$value` is a boolean that enables (`true`) or disables (`false`) the processing of blockquotes. + +## Examples + +### Disable Blockquotes + +To disable the automatic conversion of text preceded by `>` into blockquotes: + +```php +$ParsedownExtended->config()->set('quotes', false); +``` + +This documentation ensures that users have clear instructions on how to control the processing of blockquotes within their Markdown documents using ParsedownExtended, with full context provided. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Smartypants.md b/versioned_docs/version-1.3.x/Configuration/Smartypants.md new file mode 100644 index 0000000..e9cca01 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Smartypants.md @@ -0,0 +1,65 @@ +--- +title: Smartypants +--- + +# Smartypants + +## Description + +Smartypants in ParsedownExtended automatically transforms basic ASCII punctuation marks into their typographically correct HTML entities. This feature enhances the readability and aesthetic appeal of your text by converting straight quotes to curly quotes, dashes to en-dashes and em-dashes, and ellipses to their HTML equivalents. It's particularly useful for ensuring that your Markdown content maintains high typographical standards without manual adjustments. + +## ASCII to HTML Entity Conversion + +| ASCII symbol | Replacements | HTML Entities | Substitution Keys | +| ------------ | --------------- | ------------------- | ---------------------------------- | +| `''` | ‘ ’ | `‘` `’` | `"left_single_quote"`, `"right_single_quote"` | +| `""` | “ ” | `“` `”` | `"left_double_quote"`, `"right_double_quote"` | +| `<< >>` | « » | `«` `»` | `"left_angle_quote"`, `"right_angle_quote"` | +| `...` | … | `…` | `"ellipsis"` | +| `--` | – | `–` | `"ndash"` | +| `---` | — | `—` | `"mdash"` | + +## Configuration Syntax + +Configure Smartypants using the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('smarty', (bool|array) $value); +``` + +## Parameters + +Customize Smartypants with these options: + +- **smart_dashes** (boolean): Convert dashes to en-dashes and em-dashes. +- **smart_quotes** (boolean): Convert straight quotes to curly quotes. +- **smart_angled_quotes** (boolean): Convert angled quotes. +- **smart_ellipses** (boolean): Convert triple periods to ellipses. +- **substitutions** (array): Overwrite default substitutions with custom mappings. + +## Examples + +### Custom Substitutions + +To customize the substitutions for a specific language or style: + +```php +$ParsedownExtended->config()->set('smarty', [ + 'substitutions' => [ + 'left_single_quote' => '‚', // Single bottom quote + 'right_single_quote' => '‘', // Single top quote + 'left_double_quote' => '„', // Double bottom quote + 'right_double_quote' => '“' // Double top quote + ] +]); +``` + +### Enable Smartypants + +To enable Smartypants and automatically apply typographical enhancements: + +```php +$ParsedownExtended->config()->set('smarty', true); +``` + +This documentation ensures clarity and provides the full context for configuring Smartypants within ParsedownExtended, making it easy for users to apply these settings correctly in their projects. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Table of Contents.md b/versioned_docs/version-1.3.x/Configuration/Table of Contents.md new file mode 100644 index 0000000..b91fff1 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Table of Contents.md @@ -0,0 +1,70 @@ +--- +title: Table of Contents (ToC) +--- + +# Table of Contents (ToC) + +## Description + +ParsedownExtended facilitates the automatic creation of a Table of Contents (ToC) for your Markdown documents. This feature dynamically includes every heading in the document, streamlining the process by eliminating the need for manually adding anchors to each title. The ToC is generated automatically, enhancing navigability and structure in longer documents. + +## Configuration Syntax + +To enable or configure the ToC feature, use the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('toc', (bool|array) $value); +``` + +## Parameters + +Configure ToC with these options: + +- **headings** (array): Defines which heading levels to include in the ToC. +- **tag** (string): Sets a custom markdown tag for generating the ToC. +- **id** (string): Assigns a custom ID to the ToC container. + +## Generating ToC and Content Separately + +ParsedownExtended offers methods to generate the ToC and content separately: + +- **contentsList()**: Returns just the "ToC" as an HTML `
    ` list. +- **body()**: Parses content without `[toc]` tag. +- **text()**: Parses content with `[toc]` tag(s). + +Example usage: + +```php +$content = file_get_contents('sample.md'); +$Parsedown = new ParsedownExtended(); + +$body = $Parsedown->body($content); +$toc = $Parsedown->contentsList(); + +echo $toc; // Table of Contents +echo $body; // Main body content +``` + +## Examples + +### Enable ToC + +To enable the ToC feature: + +```php +$ParsedownExtended->config()->set('toc', true); +``` + +### Customize ToC + +Customize ToC with specific configurations: + +```php +$ParsedownExtended->config()->set('toc', [ + 'headings' => ['h1', 'h2', 'h3'], // Headings to include + 'tag' => '[toc]', // Custom ToC tag + 'id' => 'table-of-contents', // Custom ToC ID +]); +``` + +This documentation ensures clarity by using the correct settings structure, allowing users to properly configure and use the Table of Contents feature within ParsedownExtended. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Tables.md b/versioned_docs/version-1.3.x/Configuration/Tables.md new file mode 100644 index 0000000..c549e11 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Tables.md @@ -0,0 +1,64 @@ +--- +title: Tables +--- + +# Tables + +## Description + +Tables are a key feature in Markdown for organizing and presenting data clearly and effectively. ParsedownExtended supports the standard Markdown syntax for creating tables, which involves using hyphens (`---`) for defining columns and pipes (`|`) for separating them. For enhanced readability and compatibility, it's recommended to include pipes at the beginning and end of each row as well. + +## Configuration Syntax + +Configure table rendering in ParsedownExtended using the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('tables', (bool|array) $value); +``` + +This setting can be a boolean to enable or disable table rendering globally, or an array for more specific configurations. + +## Parameters + +- **tablespan** (boolean): Enables or disables the use of table spans (`colspan` and `rowspan`) in tables. This feature is disabled by default. + +## Examples + +### Enable Table Rendering + +To enable the rendering of tables with default settings: + +```php +$ParsedownExtended->config()->set('tables', true); +``` + +### Enable Tablespan + +To enable table spans, allowing for more complex table layouts: + +```php +$ParsedownExtended->config()->set('tables', [ + 'tablespan' => true +]); +``` + +### Disable Tables + +To completely disable table rendering: + +```php +$ParsedownExtended->config()->set('tables', false); +``` + +### Markdown Table Example + +Create a table in Markdown: + +```markdown +| Header 1 | Header 2 | Header 3 | +| -------- | -------- | -------- | +| Row 1 | Data | Data | +| Row 2 | Data | Data | +``` + +This documentation ensures that users have clear and precise instructions on how to configure and use the table rendering features within ParsedownExtended, using the correct syntax and context. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Thematic Breaks.md b/versioned_docs/version-1.3.x/Configuration/Thematic Breaks.md new file mode 100644 index 0000000..28d3d58 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Thematic Breaks.md @@ -0,0 +1,39 @@ +--- +title: Thematic Breaks +--- + +# Thematic Breaks + +## Description + +Thematic breaks, also known as horizontal rules, are a handy element in Markdown for visually dividing sections of text in your documents. A thematic break is represented by three or more consecutive hyphens (`---`), asterisks (`***`), or underscores (`___`). Regardless of the symbol used, thematic breaks produce the same visual output. + +## Configuration Syntax + +Control the rendering of thematic breaks in ParsedownExtended with the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('thematic_breaks', (bool) $value); +``` + +This setting accepts a boolean value to enable or disable thematic breaks globally. + +## Examples + +### Enable Thematic Breaks + +To enable thematic breaks with default settings: + +```php +$ParsedownExtended->config()->set('thematic_breaks', true); +``` + +### Disable Thematic Breaks + +To completely disable thematic breaks: + +```php +$ParsedownExtended->config()->set('thematic_breaks', false); +``` + +This documentation provides users with clear guidance on how to configure the rendering of thematic breaks within their Markdown documents using ParsedownExtended, with the appropriate syntax and context. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Configuration/Typographer.md b/versioned_docs/version-1.3.x/Configuration/Typographer.md new file mode 100644 index 0000000..2872b89 --- /dev/null +++ b/versioned_docs/version-1.3.x/Configuration/Typographer.md @@ -0,0 +1,46 @@ +--- +title: Typographer +--- + +# Typographer + +## Description + +ParsedownExtended includes a typographer feature that enhances your Markdown writing experience. It provides useful shortcuts for common typographic symbols, making it easier and faster to create well-formatted content. Additionally, it offers limited misspelling detection and correction. + +## Configuration Syntax + +Configure the typographer feature in ParsedownExtended using the `config()->set()` method: + +```php +$ParsedownExtended->config()->set('typographer', (bool) $value); +``` + +### Typographic Shortcodes: + +- `(c)`: Replaced with © (Copyright symbol). +- `(r)`: Replaced with ® (Registered trademark symbol). +- `(tm)`: Replaced with ™ (Trademark symbol). +- `(p)`: Replaced with ¶ (Paragraph symbol). +- `+-`: Replaced with ± (Plus-minus symbol). + +### Misspelling Detection: + +- `..` is replaced with `...` (Ellipsis). +- `.....` is replaced with `...` (Ellipsis). +- `?....` is replaced with `?..` (Question mark followed by ellipsis). +- `!....` is replaced with `!..` (Exclamation mark followed by ellipsis). + +These typographic shortcuts and limited misspelling corrections can improve the quality and consistency of your Markdown content. + +## Examples + +### Enable Typographer + +To enable the typographer feature: + +```php +$ParsedownExtended->config()->set('typographer', true); +``` + +This documentation provides clear guidance on how to configure the typographer feature within ParsedownExtended, ensuring that users can easily enable and benefit from these typographic enhancements in their Markdown content. \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Installation.md b/versioned_docs/version-1.3.x/Installation.md new file mode 100644 index 0000000..239f69a --- /dev/null +++ b/versioned_docs/version-1.3.x/Installation.md @@ -0,0 +1,51 @@ +--- +title: Installation +sidebar_position: 2 +--- + +# Installation + + +## Requirements + +Before you start using ParsedownExtended, ensure that your system meets the following requirements: + +- **PHP Version:** PHP 7.4 or higher. ParsedownExtended relies on the latest PHP features and improvements. +- **Parsedown:** The original Parsedown library version 1.7 or higher is required. This is automatically managed via Composer if you install ParsedownExtended through Composer. +- **ParsedownExtra:** If you want to use the ParsedownExtra features, you need to have the ParsedownExtra library version 0.8 or higher. This is automatically managed via Composer if you install ParsedownExtended through Composer. + +Meeting these requirements will ensure that ParsedownExtended functions correctly and efficiently on your system. + +## Using composer + +From the command line interface, navigate to your project folder then run this command: +```shell +composer require benjaminhoegh/parsedown-extended +``` +Then require the auto-loader file: +```php +require 'vendor/autoload.php'; + +$ParsedownExtended = new ParsedownExtended(); + +echo $ParsedownExtended->text('Hello _Parsedown_!'); # prints:

    Hello Parsedown!

    +// you can also parse inline markdown only +echo $ParsedownExtended->line('Hello _Parsedown_!'); # prints: Hello Parsedown! +``` + + +## Manual Installation + +Download the source code from the latest release, then include the necessary files in your project: + +```php +require 'Parsedown.php'; +require 'ParsedownExtra.php'; // optional +require 'ParsedownExtended.php'; + +$ParsedownExtended = new ParsedownExtended(); + +echo $ParsedownExtended->text('Hello _Parsedown_!'); # prints:

    Hello Parsedown!

    +// you can also parse inline markdown only +echo $ParsedownExtended->line('Hello _Parsedown_!'); # prints: Hello Parsedown! +``` \ No newline at end of file diff --git a/versioned_docs/version-1.3.x/Introduction.md b/versioned_docs/version-1.3.x/Introduction.md new file mode 100644 index 0000000..6acbdf1 --- /dev/null +++ b/versioned_docs/version-1.3.x/Introduction.md @@ -0,0 +1,29 @@ +--- +title: Introduction +sidebar_position: 1 +slug: / +--- + +# Introduction + +`ParsedownExtended` is an extension for Parsedown, offering additional features and functionalities to enhance your Markdown parsing experience. Designed to provide an easy-to-use Markdown parsing solution, it extends the capabilities of the base Parsedown library. + +Whether you need task lists, emoji support, or advanced LaTeX syntax handling, `ParsedownExtended` has you covered. This documentation will guide you through the installation, configuration, and usage of `ParsedownExtended`, helping you make the most out of this powerful tool. + +# Features + +`ParsedownExtended` includes a variety of features to enhance your Markdown parsing experience: + +- **Task Lists:** Create simple task lists in Markdown. +- **Smartypants:** Automatically convert straight quotes to curly, dashes to en-dash and em-dash, etc. +- **Emojis:** Support for rendering emojis. +- **Heading Permalinks:** Generate permalinks for your headings. +- **Table of Contents:** Automatically generate a table of contents based on headings. +- **Keystrokes:** Render keystroke combinations. +- **Marking:** Mark text within your documents for emphasis or distinction. +- **Superscript and Subscript:** Render text as superscript or subscript. +- **Diagrams Syntax Support:** Recognizes diagram syntax for integration with libraries like mermaid.js and chart.js. +- **LaTeX Syntax Support:** Detects LaTeX syntax, suitable for mathematical expressions, to be rendered with libraries like KaTeX.js. +- **Predefined Abbreviations:** Define and use abbreviations easily. +- **Customizable Options:** Extensive options for customizing each Markdown element. +- **Additional Features:** `ParsedownExtended` continuously evolves, adding more features over time. diff --git a/versioned_sidebars/version-1.3.x-sidebars.json b/versioned_sidebars/version-1.3.x-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/versioned_sidebars/version-1.3.x-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/versions.json b/versions.json index f2ceb0f..104f740 100644 --- a/versions.json +++ b/versions.json @@ -1,3 +1,4 @@ [ + "1.3.x", "1.2.x" ]