Skip to content

📖 [Docs]: README pages now use the standard module landing-page format #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
base: main
Choose a base branch
from
Open

📖 [Docs]: README pages now use the standard module landing-page format #28

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b8de2eb
Standardize README landing page
MariusStorhaug Jul 6, 2026
fc010a6
docs: restore Usage showcase with real commands; fix help snippet; dr…
MariusStorhaug Jul 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
324 changes: 22 additions & 302 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
<p>

This is a paragraph with tags

</p>
```

### Details

Generate collapsible sections with a summary title.

```powershell
Details 'More Information' {
'Detailed content goes here'
}
```

This produces:

```markdown
<details><summary>More Information</summary>
<p>

Detailed content goes here

</p>
</details>
```

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
<details><summary>More Information</summary>
<p>

Detailed content goes here

<details><summary>Nested Information</summary>
<p>

Nested content goes here

</p>
</details>

</p>
</details>
```


### 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
<details><summary>This is the detail title</summary>
<p>

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

<details><summary>Should be able to call nested details</summary>
<p>

Some string content here too

</p>
</details>

</p>
</details>


<p>

This is a paragraph

</p>

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.
Loading