diff --git a/README.md b/README.md index 7380886..994aed4 100644 --- a/README.md +++ b/README.md @@ -1,336 +1,27 @@ # Markdown -A PowerShell module that converts a custom DSL into Markdown documents with ease. It empowers you to programmatically generate well-structured -Markdown—featuring headings, collapsible details, code fences, and tables — using intuitive DSL commands. Built for automation and fully -cross-platform, this module challenges the conventional approach to documentation generation. +Markdown is a PowerShell module for building Markdown content. ## Installation -To install the module from the PowerShell Gallery, run the following commands: +Install the module from the PowerShell Gallery: ```powershell Install-PSResource -Name Markdown Import-Module -Name Markdown ``` -## Usage +## Documentation -The `Markdown` module introduces a Domain Specific Language (DSL) that simplifies the creation of Markdown files. With straightforward commands, you -can generate headings, details blocks, fenced code blocks, and tables without manually formatting Markdown. +Documentation is published at [psmodule.io/Markdown](https://psmodule.io/Markdown/). -### Heading +Use PowerShell help and command discovery for module details: -Create Markdown headings by specifying the level, title, and content. - -```powershell -Heading 1 'Title' { - 'Content under the title' -} -``` - -This produces: - -```markdown -# Title - -Content under the title -``` - -Supports nested headings. - -```powershell -Heading 1 'Title' { - 'Content under the title' - - Heading 2 'Nested Title' { - 'Content under the nested title' - } -} -``` - -This produces: - -```markdown -# Title - -Content under the title - -## Nested Title - -Content under the nested title -``` - -### Paragraph - -Create a paragraph of text. - -```powershell -Paragraph { - 'This is a paragraph' -} -``` - -This produces: - -```markdown - -This is a paragraph - -``` - -Supports tags for inline formatting. - -```powershell -Paragraph { - 'This is a paragraph with tags' -} -Tags -``` - -This produces: - -```markdown -

- -This is a paragraph with tags - -

-``` - -### Details - -Generate collapsible sections with a summary title. - -```powershell -Details 'More Information' { - 'Detailed content goes here' -} -``` - -This produces: - -```markdown -
More Information -

- -Detailed content goes here - -

-
-``` - -Supports nested details blocks. - -```powershell -Details 'More Information' { - 'Detailed content goes here' - - Details 'Nested Information' { - 'Nested content goes here' - } -} -``` - -This produces: - -```markdown -
More Information -

- -Detailed content goes here - -

Nested Information -

- -Nested content goes here - -

-
- -

-
-``` - - -### CodeBlock - -Create fenced code blocks for any programming language. - -```powershell -CodeBlock 'PowerShell' { - Get-Process -} -``` - -This produces: - -````markdown ```powershell -Get-Process +Get-Command -Module Markdown +Get-Help -Examples ``` -```` - -It can also execute PowerShell code directly and use the output in the code block (using the `-Execute` switch). - -```powershell -CodeBlock 'PowerShell' { - @( - [PSCustomObject]@{ Name = 'John Doe'; Age = 30 } - [PSCustomObject]@{ Name = 'Jane Doe'; Age = 25 } - ) -} -Execute -``` - -This produces: - -````markdown -```powershell - -Name Age ----- --- -John Doe 30 -Jane Doe 25 - -``` -```` - -### Table - -Convert a collection of PowerShell objects into a Markdown table. - -```powershell -Table { - @( - [PSCustomObject]@{ Name = 'John Doe'; Age = 30 } - [PSCustomObject]@{ Name = 'Jane Doe'; Age = 25 } - ) -} -``` - -This produces: - -```markdown -| Name | Age | -| - | - | -| John Doe | 30 | -| Jane Doe | 25 | -``` - -### Example: Full Markdown Document Generation - -Below is an example DSL script that demonstrates how to compose a complete Markdown document: - -```powershell -Heading 1 'This is the section title' { - 'Some string content here' - - Heading 2 'Should be able to call nested sections' { - 'Some string content here too' - - Details 'This is the detail title' { - 'Some string content here' - - CodeBlock 'PowerShell' { - Get-Process - } - - Details 'Should be able to call nested details' { - 'Some string content here too' - } - } - - Paragraph { - 'This is a paragraph' - } -Tags - - 'This is the end of the section' - } - - CodeBlock 'PowerShell' { - @( - [PSCustomObject]@{ Name = 'John Doe'; Age = 30 } - [PSCustomObject]@{ Name = 'Jane Doe'; Age = 25 } - ) - } -Execute - - Table { - @( - [PSCustomObject]@{ Name = 'John Doe'; Age = 30 } - [PSCustomObject]@{ Name = 'Jane Doe'; Age = 25 } - ) - } - - - 'This is the end of the document' -} -``` - -The DSL above automatically generates the following Markdown: - -````markdown -# This is the section title - -Some string content here -## Should be able to call nested sections - -Some string content here too -
This is the detail title -

- -Some string content here -```powershell -Get-Process -``` - -

Should be able to call nested details -

- -Some string content here too - -

-
- -

-
- - -

- -This is a paragraph - -

- -This is the end of the section - -```powershell - -Name Age ----- --- -John Doe 30 -Jane Doe 25 - - -``` - -| Name | Age | -| - | - | -| John Doe | 30 | -| Jane Doe | 25 | - -This is the end of the document - -```` ## Contributing -Whether you’re a user with valuable feedback or a developer with innovative ideas, your contributions are welcome. Here’s how you can get involved: - -### For Users - -If you encounter unexpected behavior, error messages, or missing functionality, please open an issue in the repository. -Your insights are crucial for refining the module. - -### For Developers - -We welcome contributions that enhance automation, extend functionality, or improve cross-platform compatibility. -Please review the [Contribution Guidelines](CONTRIBUTING.md) before submitting pull requests. Whether you want to tackle an existing -issue or propose a new feature, your ideas are essential for pushing the boundaries of what's possible with PowerShell documentation automation. +Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements.