Skip to content

Commit 30df21f

Browse files
smnandresmnandre
committed
initial release
0 parents  commit 30df21f

196 files changed

Lines changed: 9637 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/.git* export-ignore
2+
/.php-cs-fixer.dist.php export-ignore
3+
/phpstan.dist.neon export-ignore
4+
/phpunit.dist.xml export-ignore
5+
/tests/ export-ignore

‎.github/workflows/CI.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ "*" ]
6+
pull_request:
7+
branches: [ "*" ]
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
13+
concurrency:
14+
group: ${{ github.workflow }}-${{ github.ref }}
15+
cancel-in-progress: true
16+
17+
jobs:
18+
19+
cs:
20+
uses: phpalto/.github/.github/workflows/CS.yml@main
21+
22+
sa:
23+
uses: phpalto/.github/.github/workflows/SA.yml@main
24+
25+
tests:
26+
strategy:
27+
fail-fast: false
28+
matrix:
29+
php: ['8.3', '8.4', '8.5']
30+
uses: phpalto/.github/.github/workflows/tests.yml@main
31+
with:
32+
php-version: ${{ matrix.php }}

‎.github/workflows/split.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Split Packages
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
reference:
7+
description: 'Git ref to split (branch, tag, or SHA)'
8+
required: true
9+
default: 'main'
10+
11+
jobs:
12+
split:
13+
runs-on: ubuntu-latest
14+
15+
strategy:
16+
fail-fast: false
17+
matrix:
18+
package:
19+
- { prefix: 'src/Extension/CodeBlockTitle', repo: 'commonmark-code-block-title' }
20+
- { prefix: 'src/Extension/ContentSlicer', repo: 'commonmark-content-slicer' }
21+
- { prefix: 'src/Extension/HeadingLevel', repo: 'commonmark-heading-level' }
22+
- { prefix: 'src/Extension/Import', repo: 'commonmark-import' }
23+
- { prefix: 'src/Extension/Include', repo: 'commonmark-include' }
24+
- { prefix: 'src/Extension/LinkRewriter', repo: 'commonmark-link-rewriter' }
25+
- { prefix: 'src/Extension/Source', repo: 'commonmark-source' }
26+
- { prefix: 'src/Extension/TableOfContents', repo: 'commonmark-table-of-contents' }
27+
- { prefix: 'src/Extension/Tabs', repo: 'commonmark-tabs' }
28+
29+
steps:
30+
- name: Checkout
31+
uses: actions/checkout@v4
32+
with:
33+
fetch-depth: 0
34+
35+
- name: Split ${{ matrix.package.prefix }}
36+
uses: claudiodekker/splitsh-action@v1.0.0
37+
env:
38+
# Personal Access Token with push access to split repositories
39+
GITHUB_TOKEN: ${{ secrets.MONOREPO_SPLIT_TOKEN }}
40+
with:
41+
prefix: ${{ matrix.package.prefix }}
42+
remote: https://github.com/${{ vars.SPLIT_REPO_OWNER }}/${{ matrix.package.repo }}.git
43+
reference: ${{ inputs.reference }}
44+
as_tag: ${{ startsWith(inputs.reference, 'refs/tags/') || startsWith(inputs.reference, 'v') }}

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
/.phpunit.cache/
2+
/vendor/
3+
/.php-cs-fixer.cache
4+
/composer.lock
5+
src/**/composer.lock
6+
/phpstan.neon
7+
/phpunit.xml

‎.php-cs-fixer.dist.php‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?php
2+
3+
$header = <<<'EOF'
4+
This file is part of the ALTO Commonmark package.
5+
6+
© 2025–present Simon André
7+
8+
For full copyright and license information, please see
9+
the LICENSE file distributed with this source code.
10+
EOF;
11+
12+
$finder = (new PhpCsFixer\Finder())
13+
->in(__DIR__)
14+
->exclude([
15+
'vendor/',
16+
'tests/Fixtures/',
17+
]);
18+
19+
return (new PhpCsFixer\Config())
20+
->setParallelConfig(PhpCsFixer\Runner\Parallel\ParallelConfigFactory::detect())
21+
->setFinder($finder)
22+
->setRiskyAllowed(true)
23+
->setRules([
24+
'@PER-CS' => true,
25+
'@Symfony' => true,
26+
'declare_strict_types' => true,
27+
'header_comment' => ['header' => $header],
28+
]);

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CHANGELOG
2+
3+
## [Unreleased]
4+
5+
## [0.1.0] - 2025-11-15
6+
7+
- Initial public release
8+
- Added Code Block Title extension
9+
- Added Heading Level Down extension
10+
- Added Heading Section extension
11+
- Added Link Rewriter extension

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025-present Simon André
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Alto CommonMark
2+
3+
Reusable `league/commonmark` extensions in a monorepo, installable as either the umbrella package `alto/commonmark` or as standalone per-extension packages.
4+
5+
## Installation
6+
7+
```bash
8+
composer require alto/commonmark
9+
```
10+
11+
`alto/commonmark` declares `replace` on all standalone packages, so dependency resolution stays compatible whether you install one or all.
12+
13+
| Extension | Description | GitHub | Packagist |
14+
|-----------|-------------|--------|-----------|
15+
| CodeBlockTitle | Titled fenced code blocks rendered as `<figure>` | [GitHub](https://github.com/PhpAlto/commonmark-code-block-title) | [Packagist](https://packagist.org/packages/alto/commonmark-code-block-title) |
16+
| ContentSlicer | Wraps heading sections in semantic `<section>` elements | [GitHub](https://github.com/PhpAlto/commonmark-content-slicer) | [Packagist](https://packagist.org/packages/alto/commonmark-content-slicer) |
17+
| HeadingLevel | Shift or remap heading levels across the document | [GitHub](https://github.com/PhpAlto/commonmark-heading-level) | [Packagist](https://packagist.org/packages/alto/commonmark-heading-level) |
18+
| Import | Import file contents into code blocks with line ranges | [GitHub](https://github.com/PhpAlto/commonmark-import) | [Packagist](https://packagist.org/packages/alto/commonmark-import) |
19+
| Include | Inline-include Markdown fragments for doc composition | [GitHub](https://github.com/PhpAlto/commonmark-include) | [Packagist](https://packagist.org/packages/alto/commonmark-include) |
20+
| LinkRewriter | Rewrite links & images via base URI, map, or regex | [GitHub](https://github.com/PhpAlto/commonmark-link-rewriter) | [Packagist](https://packagist.org/packages/alto/commonmark-link-rewriter) |
21+
| Source | Embed source files with line numbers and highlighting | [GitHub](https://github.com/PhpAlto/commonmark-source) | [Packagist](https://packagist.org/packages/alto/commonmark-source) |
22+
| TableOfContents | Auto-generated TOC from headings via `@toc` | [GitHub](https://github.com/PhpAlto/commonmark-table-of-contents) | [Packagist](https://packagist.org/packages/alto/commonmark-table-of-contents) |
23+
| Tabs | Accessible ARIA tabbed UI from a simple `@tabs` directive | [GitHub](https://github.com/PhpAlto/commonmark-tabs) | [Packagist](https://packagist.org/packages/alto/commonmark-tabs) |
24+
25+
## Extensions
26+
27+
### CodeBlockTitle
28+
The detail that signals craft — adds a `title="..."` to any fenced code block and wraps it in a semantic `<figure>`/`<figcaption>`. One small thing that makes a doc site feel finished.
29+
30+
````markdown
31+
```php title="hello.php"
32+
echo "Hello";
33+
```
34+
````
35+
36+
```html
37+
<figure class="code-block has-title" data-title="hello.php">
38+
<figcaption class="code-title">hello.php</figcaption>
39+
<pre><code class="language-php">echo "Hello";
40+
</code></pre>
41+
</figure>
42+
```
43+
44+
[Doc](src/Extension/CodeBlockTitle/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/CodeBlockTitle) · [Packagist](https://packagist.org/packages/alto/commonmark-code-block-title)
45+
46+
---
47+
48+
### ContentSlicer
49+
The rarest one in the set. Most processors stop at rendering headings as tags — this one restructures the entire document into a properly nested `<section>` tree, giving CSS selectors, JavaScript, and accessibility tooling something real to work with. No custom syntax needed.
50+
51+
```markdown
52+
## Subtopic 1
53+
More content.
54+
## Subtopic 2
55+
Final content.
56+
```
57+
58+
```html
59+
<section><h2>Subtopic 1</h2><p>More content.</p></section>
60+
<section><h2>Subtopic 2</h2><p>Final content.</p></section>
61+
```
62+
63+
[Doc](src/Extension/ContentSlicer/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/ContentSlicer) · [Packagist](https://packagist.org/packages/alto/commonmark-content-slicer)
64+
65+
---
66+
67+
### HeadingLevel
68+
The one you don't need until you really do — then it's irreplaceable. Shifts, remaps, or transforms heading levels when embedding content from one context into another without heading hierarchy collisions.
69+
70+
```markdown
71+
# Title
72+
## Section
73+
```
74+
75+
```html
76+
<!-- with down: 1 -->
77+
<h2>Title</h2>
78+
<h3>Section</h3>
79+
```
80+
81+
[Doc](src/Extension/HeadingLevel/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/HeadingLevel) · [Packagist](https://packagist.org/packages/alto/commonmark-heading-level)
82+
83+
---
84+
85+
### Import
86+
Solves copy-paste drift between your docs and your source code. Pulls external file content directly into a code block — with line-range selection, language hinting, and depth-limited circular-import protection.
87+
88+
```markdown
89+
@import "src/Auth.php" {lines: 1-30, lang: php}
90+
```
91+
92+
```html
93+
<pre><code class="language-php">// src/Auth.php lines 1–30
94+
</code></pre>
95+
```
96+
97+
[Doc](src/Extension/Import/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/Import) · [Packagist](https://packagist.org/packages/alto/commonmark-import)
98+
99+
---
100+
101+
### Include
102+
The backbone of large documentation sets. Pulls in and fully parses markdown fragments inline — making one-file-per-section composition possible without a build system.
103+
104+
```markdown
105+
@include "parts/intro.md"
106+
```
107+
108+
```html
109+
<h2>Introduction</h2>
110+
<p>This is the introduction section.</p>
111+
```
112+
113+
[Doc](src/Extension/Include/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/Include) · [Packagist](https://packagist.org/packages/alto/commonmark-include)
114+
115+
---
116+
117+
### LinkRewriter
118+
Indispensable plumbing for any hosted documentation setup. Decouples your markdown from your deployment URL with a composable chain of rewrite rules — base URI, exact maps, regex, and custom callbacks — applied in sequence.
119+
120+
```markdown
121+
[Guide](/getting-started)
122+
![Logo](/assets/logo.svg)
123+
```
124+
125+
```html
126+
<!-- with base_uri: https://docs.example.com -->
127+
<a href="https://docs.example.com/getting-started">Guide</a>
128+
<img src="https://docs.example.com/assets/logo.svg" alt="Logo">
129+
```
130+
131+
[Doc](src/Extension/LinkRewriter/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/LinkRewriter) · [Packagist](https://packagist.org/packages/alto/commonmark-link-rewriter)
132+
133+
---
134+
135+
### Source
136+
The flagship of the set. Embeds a real file — not a copy — directly into your documentation, with syntax detection, line-range selection, line numbers, and per-line highlighting. Your docs stay in sync with your code by definition.
137+
138+
```markdown
139+
@source "src/Service.php" {lines: 9-11, numbers: true, highlight: "9,11"}
140+
```
141+
142+
```html
143+
<div class="source-block">
144+
<div class="source-path">src/Service.php</div>
145+
<pre><code class="language-php"><span class="line highlighted"><span class="line-number">9</span> public function add(int $a, int $b): int</span>
146+
<span class="line"><span class="line-number">10</span> {</span>
147+
<span class="line highlighted"><span class="line-number">11</span> return $a + $b;</span></code></pre>
148+
</div>
149+
```
150+
151+
[Doc](src/Extension/Source/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/Source) · [Packagist](https://packagist.org/packages/alto/commonmark-source)
152+
153+
---
154+
155+
### TableOfContents
156+
A must-have for any document longer than a page. Drop `@toc` where you want the contents list — headings are collected, IDs assigned, and a navigable list rendered in one pass.
157+
158+
```markdown
159+
@toc {min: 2}
160+
## Introduction
161+
## Setup
162+
```
163+
164+
```html
165+
<div class="table-of-contents" id="toc">
166+
<ul>
167+
<li><a href="#introduction">Introduction</a></li>
168+
<li><a href="#setup">Setup</a></li>
169+
</ul>
170+
</div>
171+
```
172+
173+
[Doc](src/Extension/TableOfContents/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/TableOfContents) · [Packagist](https://packagist.org/packages/alto/commonmark-table-of-contents)
174+
175+
---
176+
177+
### Tabs
178+
One directive, fully accessible tabbed UI, zero JavaScript to write. Wraps content in proper ARIA `tablist`/`tab`/`tabpanel` roles with a self-contained switching script.
179+
180+
````markdown
181+
@tabs
182+
@tab "PHP"
183+
```php
184+
echo 'Hello';
185+
```
186+
@tab "JS"
187+
```js
188+
console.log('Hello');
189+
```
190+
@endtabs
191+
````
192+
193+
```html
194+
<div class="tab-group" data-tabs-id="tabs-1">
195+
<div class="tab-list" role="tablist">
196+
<button class="tab active" role="tab" aria-selected="true" aria-controls="tabs-1-panel-0">PHP</button>
197+
<button class="tab" role="tab" aria-selected="false" aria-controls="tabs-1-panel-1">JS</button>
198+
</div>
199+
<div class="tab-panels">
200+
<div class="tab-panel" id="tabs-1-panel-0" role="tabpanel">…</div>
201+
<div class="tab-panel" id="tabs-1-panel-1" role="tabpanel">…</div>
202+
</div>
203+
</div>
204+
```
205+
206+
[Doc](src/Extension/Tabs/README.md) · [GitHub](https://github.com/alto/commonmark/tree/main/src/Extension/Tabs) · [Packagist](https://packagist.org/packages/alto/commonmark-tabs)
207+
208+
## Support
209+
210+
If Alto CommonMark is useful to your project, [sponsoring on GitHub](https://github.com/sponsors/smnandre) is a great way to support continued development — and it's always appreciated.
211+
212+
## License
213+
214+
MIT. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)