Download the PHP package markdown-office/commonmark-generic-directives without Composer
On this page you can find all versions of the php package markdown-office/commonmark-generic-directives. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download markdown-office/commonmark-generic-directives
More information about markdown-office/commonmark-generic-directives
Files in markdown-office/commonmark-generic-directives
Package commonmark-generic-directives
Short Description A standalone league/commonmark extension implementing the Generic Directives RFC: container (:::), leaf (::) and text (:) directives with attribute, #id and .class syntax.
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package commonmark-generic-directives
CommonMark Generic Directives
A league/commonmark extension implementing the
Generic Directives RFC:
container (:::), leaf (::) and text (:) directives.
One syntax, three shapes, and nothing to register to make it parse.
Installation
Requires PHP 8.2 or newer and league/commonmark 2.10 or newer.
Usage
The default renderer preserves everything rather than choosing for you: the element carries the directive's name, and every attribute is reproduced. What a directive means is yours to decide — register your own renderer over it.
The container above is checked against the opening example; see Tests for how.
Writing your own renderer
The three shapes
| Shape | Written | Contains | Name |
|---|---|---|---|
| Text | :name[label]{attrs} |
nothing — it sits in a paragraph | DirectiveInline |
| Leaf | ::name[label]{attrs} |
nothing — it is one line | DirectiveBlock |
| Container | :::name{attrs} … ::: |
any Markdown | DirectiveBlock |
The colon count is the whole difference. A container opens with three or more colons and closes on a line of at least as many, so a body can show a nested three-colon container by opening its own with four.
The RFC lets the parts of a block directive be spaced out for readability — :: name,
:::eval [label] {.python}. An inline directive does not get that: : is how prose
introduces a clause.
A container may be written without a name, and then it is a div carrying the attributes that followed it.
The opening line may also end in colons, which mean nothing — as long as something else is on
the line, because ::: on its own is how a container closes.
Attributes
#id and .class may also be written bare after the name — :::note#lead.terse means
the same thing — and several .class entries accumulate rather than replace each other.
Values are read with typed accessors rather than by hand:
Unknown names: permissive or strict
With no registry the extension is permissive and parses any well-formed directive, which
is what the RFC describes. Given a registry it is strict, and an unregistered name raises
UnknownDirective naming the alternatives:
Use strict mode when a machine writes the Markdown. The alternative to an error is a document that renders without the block it asked for and says nothing about why — which is the worst outcome available, because nothing in the output looks wrong.
A bare name allows every shape; name:type allows one. Names match case-insensitively,
because a document cannot be asked to care about case.
The AST
__toString() round-trips: ::image[Chart]{src="a.png"} in, the same string out.
What is deliberately not a directive
These are left as literal text, which is the recoverable outcome:
Note: prose— a colon before a space3:2,10:30— a colon between digitsstatus:error— a word before the colon:::a— four spaces of indent, which is code in CommonMark- anything inside a fenced or indented code block
That last one is structural rather than a rule this package applies: CommonMark does not
look for new block starts inside a block that is not a container, so a ::: inside a
fence is code before this extension is consulted.
The default renderer's HTML is namespaced
Author attributes are written into the data- namespace:
That is not tidiness. An onclick written into a page that later runs scripts is a
script, and deciding which attribute names are dangerous by keeping a list means the list
is only ever correct until someone invents an event. Namespacing needs no list to maintain.
data-directive is reserved and carries the directive's real name; an author attribute
that would land on it is dropped rather than renamed. A consumer that wants real
attributes reads the node rather than this markup.
Tests
The suite is 100% covered and analysed at PHPStan level 9. Every example on this page
is executed by tests/Readme/ExamplesTest.php and every claim in the prose by
tests/Readme/ClaimsTest.php, so neither can drift from the code without the build failing.
Licence
MIT. See LICENSE.
