Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sinnbeck/markdom
A markdown parser for laravel for making beautiful html
https://github.com/sinnbeck/markdom
codehighlight commonmark html laravel livewire markdown
Last synced: 8 days ago
JSON representation
A markdown parser for laravel for making beautiful html
- Host: GitHub
- URL: https://github.com/sinnbeck/markdom
- Owner: sinnbeck
- Created: 2020-10-23T08:25:04.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-13T08:10:07.000Z (8 months ago)
- Last Synced: 2024-10-14T07:21:51.903Z (25 days ago)
- Topics: codehighlight, commonmark, html, laravel, livewire, markdown
- Language: PHP
- Homepage:
- Size: 221 KB
- Stars: 64
- Watchers: 2
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://packagist.org/packages/sinnbeck/markdom)
[](https://packagist.org/packages/sinnbeck/markdom)
# Introduction
Markdom is a laravel package to make it simple to convert markdown to beautifully rendered html. It adds classes and allows you to automatically do code highlighting.
## Installation
Install the package using composer
```
$ composer require sinnbeck/markdom
```
After that is a good idea to add the facade to your `config/app.php` aliases array.
```
'Markdom' => Sinnbeck\Markdom\Facades\Markdom::class,
```
## Publish the config
To publish the config file simply run the following to add `markdom.php` to your config directory.
```
php artisan vendor:publish --tag=markdom-config
```
## Usage
Markdom comes with a blade helper to easily convert markdown to html
```
@markdom($markdown)
```
You can also call it though the facade
```
Markdom::toHtml($markdown)
```
## Configuration
The main feature of Markdom is to add classes to your rendered html. This requires you to set up a class map in `markdom.php`. This determines which elements are getting what classes.
Here is a quick example using TailwindCss syntax.
```
'classes' => [
'h1' => 'text-3xl font-bold mt-1 mb-2 border-b',
'h2' => 'text-2xl font-bold my-1 border-b',
'h3' => 'text-xl font-bold my-1',
'p' => 'py-2',
'ul' => 'list-disc list-inside',
'ul ul' => 'pl-8 list-disc list-inside',
'ol' => 'list-decimal list-inside',
'pre' => 'my-1'
],
```
The key can be any css selector, meaning you can also do `ul > li > ul` or even `.classname`. The classes are parsed in the order that they are listed in the config, meaning you can add additional classes to those set before.
```
'classes' => [
'h1' => 'title text-3xl ',
'h2' => 'title text-2xl',
'h3' => 'title text-xl',
'.title' => 'font-bold border-b',
],
```
The above will add the class title to the header elements, and the then `'font-bold border-b'` to each. \
Result:
```
Title
Subtitle
More
```
### Adding id and href
Markdom makes it simple to add id and links (``) to headings (for use in documentation).
Just set the `links.enabled` to `true` in the `markdom.php` config file, and Markdom takes care of the rest.
Check the documentation if the config, for configuration options.
## Markdown configuration
It is possible to tweak the parsing of markdown. Under the hood, Mardom uses `league/commonmark`, meaning all settings under the `commonmark` key, is just sent directly to CommonMark.
See a list of available settings here: https://commonmark.thephpleague.com/2.3/configuration/#configuration
### Markdown extensions
CommonMark comes with a lot of extensions. These can be added to the `commonmark_extensions` array which will make them automatically load.
See a list of available extensions here: https://commonmark.thephpleague.com/2.3/extensions/overview/
## Code highlighting
If you are using markdown for parsing code, you may enable the code highlighter, by setting `MARKDOM_CODE_HIGHLIGHT=true` in your .env file. This will automatically add highlight.js classes to the code found in code tags.
CommonMark will convert \`somecode\` and \
\`\`\` \
somecode \
\`\`\` \
to `somecode` and `
somecode
` which will be passed to `scrivo/highlight.php` (a php implementation of highlight.js).
### Highlight theme and css
It is possible to have your code styled automatically. This can be done simply by adding the `@markdomStyles()` directive to your page. This will embed the highlight.js css into your page. You can pass the name of a theme to the method, to get a specific stylesheet `@markdomStyles('purebasic')`
### Highlighting theme
Highlight.js supports 91 themes currently. You can get an array of these themes by using `Markdom::getAvailableThemes()`. This can be useful for rendering a select, if the user is allowed to select theme.
```
@foreach(Markdom::getAvailableThemes() as $style)
{{$style}}
@endforeach
```
### Examples
Controller (markdown can be also be loaded from database or a file)
```
public function index()
{
$markdown =
<<foo = 'bar';
\```
Inline code `const $x = [1, 2, 3];`
### Text formatting
**Bold** \
__Bold__ \
_Italic_ \
~~Crossed~~
### Escaped html
alert()
markdown;
return view('markdown.index', compact('markdown'));
}
```
index.blade.php
```
@extends('layouts.app')
@section('content')
@markdom($markdown)
@endsection
```
#### Livewire
Markdom also works great with Livewire and does not require any javascript.
You can get a working example of an autoupdating markdown editor using livewire here: https://github.com/sinnbeck/markdom-livewire
#### Update notice!
If you are upgrading from version 1.x to 2.x, be aware that the config format has changed alot due to changes in commonmark! It is therefor a good idea to check the new example config file in the /config directory.
## Testing
Run tests with
```
vendor/bin/pest
```
## Todo
- [ ] Handle loading of highlight styles using