121 lines
6.1 KiB
Markdown
121 lines
6.1 KiB
Markdown
# Contributing to Marked
|
|
|
|
- [ ] Fork `markedjs/marked`.
|
|
- [ ] Clone the library locally using GitHub Desktop or the command line.
|
|
- [ ] Make sure you are on the `master` branch.
|
|
- [ ] Be sure to run `npm install` or `npm update`.
|
|
- [ ] Create a branch.
|
|
- [ ] Update code in `src` folder. (`lib` folder is for auto compiled code)
|
|
- [ ] Run `npm run test:all`, fix any broken things (for linting, you can run `npm run lint` to have the linter fix them for you).
|
|
- [ ] Run `npm run build:reset` to remove changes to compiled files.
|
|
- [ ] Submit a Pull Request.
|
|
|
|
<h2 id="design-principles">Design principles</h2>
|
|
|
|
Marked tends to favor following the SOLID set of software design and development principles; mainly the [single responsibility](https://en.wikipedia.org/wiki/Single_responsibility_principle) and [open/closed principles](https://en.wikipedia.org/wiki/Open/closed_principle):
|
|
|
|
- **Single responsibility:** Marked, and the components of Marked, have the single responsibility of converting Markdown strings into HTML.
|
|
- **Open/closed:** Marked favors giving developers the means to easily extend the library and its components over changing Marked's behavior through configuration options.
|
|
|
|
<h2 id="priorities">Priorities</h2>
|
|
|
|
We think we have our priorities sorted to build quality in.
|
|
|
|
The following table lists the ticket type labels we use when there is work to be done on the code either through an Issue or a PR; in priority order.
|
|
|
|
|Ticket type label |Description |
|
|
|:----------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
|L0 - security |A security vulnerability within the Marked library is discovered. |
|
|
|L1 - broken |Valid usage results in incorrect output compared to [supported specifications](/#specifications) OR causes marked to crash AND there is no known workaround for the issue. |
|
|
|L2 - annoying |Similar to L1 - broken only there is a known workaround available for the issue. |
|
|
|RR - refactor and re-engineer |Results in an improvement to developers using Marked (improved readability) or end-users (faster performance) or both. |
|
|
|NFS - new feature (spec related) |A capability Marked does not currently provide but is in one of the [supported specifications](/#specifications) |
|
|
|NFU - new feature (user requested) |A capability Marked does not currently provide but has been requested by users of Marked. |
|
|
|NFE - new feature (should be an extension) |A capability Marked does not currently provide and is not part of a spec. |
|
|
|
|
<h2 id="test-early-often-and-everything">Test early, often, and everything</h2>
|
|
|
|
We try to write test cases to validate output (writing tests based on the [supported specifications](/#specifications)) and minimize regression (writing tests for issues fixed). Therefore, if you would like to contribute, some things you should know regarding the test harness.
|
|
|
|
|Location |Description |
|
|
|:---------------------|:--------------------------------------------------------------------------------------------------------------|
|
|
|/test/specs/commonmark|Tests for [CommonMark](https://spec.commonmark.org/current/) compliance |
|
|
|/test/specs/gfm |Tests for [GFM](https://github.github.com/gfm/) compliance |
|
|
|/test/specs/new |Tests not related to the original `markdown.pl`. |
|
|
|/test/specs/original |Tests validating against the original `markdown.pl`. |
|
|
|/test/specs/redos |Tests for [ReDOS](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) vulnerabilities|
|
|
|
|
If your test uses features or options, assuming `gfm` is set to `false`, for example, you can add [front-matter](https://www.npmjs.com/package/front-matter) to the top of
|
|
your `.md` file
|
|
|
|
``` yml
|
|
---
|
|
gfm: false
|
|
---
|
|
```
|
|
|
|
## Submitting PRs and Issues
|
|
|
|
Marked provides templates for submitting both pull requests and issues. When you begin creating a new PR or issue, you will see instructions on using the template.
|
|
|
|
The PR templates include checklists for both the submitter and the reviewer, which, in most cases, will not be the same person.
|
|
|
|
## Scripts
|
|
|
|
When it comes to NPM commands, we try to use the native scripts provided by the NPM framework.
|
|
|
|
To run the tests:
|
|
|
|
``` bash
|
|
npm test
|
|
```
|
|
|
|
To test whether you are using the standard syntax rules for the project:
|
|
|
|
```bash
|
|
npm run test:lint
|
|
```
|
|
|
|
To see time comparisons between Marked and other popular Markdown libraries:
|
|
|
|
```bash
|
|
npm run bench
|
|
```
|
|
|
|
To see the compiled rules from `src/rules.js`:
|
|
|
|
```bash
|
|
npm run rules
|
|
```
|
|
|
|
You can specify one or more `rule path`s to only show certain rules:
|
|
|
|
```bash
|
|
npm run rules -- block.gfm.item inline.pedantic.br
|
|
|
|
{
|
|
block: {
|
|
gfm: {
|
|
item: /^( *)((?:[*+-]|\\d{1,9}\\.)) ?[^\\n]*(?:\\n(?!\\1(?:[*+-]|\\d{1,9}\\.) ?)[^\\n]*)*/gm
|
|
}
|
|
},
|
|
inline: {
|
|
pedantic: {
|
|
br: /^( {2,}|\\\\)\\n(?!\\s*$)/
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
To check for (and fix) standardized syntax (lint):
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
To build your own es5, esm, and minified versions of Marked:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|