diff --git a/README.md b/README.md index 7380886..f919e80 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # 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 cross-platform PowerShell module for building Markdown content programmatically. It provides a small set of +composable commands that let you generate well-structured Markdown — headings, paragraphs, collapsible details, fenced code +blocks, and tables — directly from PowerShell, making it a natural fit for automated documentation generation. ## 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 @@ -15,322 +15,42 @@ Import-Module -Name Markdown ## Usage -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. +Each command returns a Markdown-formatted string, and they nest inside one another so you can compose a whole document +from PowerShell. -### Heading - -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. +### Example: Build a section with a table and code block ```powershell -Heading 1 'Title' { - 'Content under the title' +Set-MarkdownSection -Level 2 -Title 'Running processes' -Content { + 'A snapshot of the current processes:' - Heading 2 'Nested Title' { - 'Content under the nested title' + Set-MarkdownTable -InputScriptBlock { + Get-Process | Select-Object -First 3 Name, Id } -} -``` - -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' + Set-MarkdownCodeBlock -Language 'powershell' -Content { + Get-Process | Select-Object -First 3 Name, Id } } ``` -This produces: - -```markdown -
More Information -

- -Detailed content goes here - -

Nested Information -

- -Nested content goes here - -

-
- -

-
-``` - - -### CodeBlock - -Create fenced code blocks for any programming language. +### Example: Add a collapsible details block ```powershell -CodeBlock 'PowerShell' { - Get-Process -} -``` - -This produces: - -````markdown -```powershell -Get-Process -``` -```` - -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 } - ) +Set-MarkdownDetails -Title 'More information' -Content { + Set-MarkdownParagraph -Content { + 'Content inside a details block stays hidden until expanded.' } - - - 'This is the end of the document' } ``` -The DSL above automatically generates the following Markdown: +## Documentation -````markdown -# This is the section title +Documentation is published at [psmodule.io/Markdown](https://psmodule.io/Markdown/). -Some string content here -## Should be able to call nested sections +Use PowerShell help and command discovery for module details: -Some string content here too -
This is the detail title -

- -Some string content here ```powershell -Get-Process +Get-Command -Module Markdown +Get-Help -Name Set-MarkdownTable -Examples ``` - -

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.