https://github.com/l2silver/proofreadme
https://github.com/l2silver/proofreadme
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/l2silver/proofreadme
- Owner: l2silver
- License: mit
- Created: 2023-03-12T13:01:48.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-03-16T01:44:33.000Z (over 3 years ago)
- Last Synced: 2025-06-23T05:02:48.880Z (about 1 year ago)
- Language: TypeScript
- Size: 81.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Proofreadme
Readme enforcer/validation tool. Make sure your readme is still valid by running the logic in the readme.
## Example
````
// README-example.md
# Welcome
Welcome to foobar. To setup and start the app use the following commands
```
# @prm-ignore-1 (ignores the next line in proofreadme validation)
npm install
# @prm-wait-until-regex-output-/Listening on port/ (wait for response before allowing the next action to occur)
npm start
```
To run e2e tests on the app, use
```
# @prm-final (when this command runs successfully, close all processes and exit with success signal)
npm run e2e
```
````
---
```
$ proofreadme -p README-example.md -h # Welcome
> npm start ...
> npm run e2e ...
> README-example.md run successfully
```
### Explanation
We run proofreadme on the `README-example.md` file. First, we choose the header that we want to run commands from. We've chosen `### Welcome`. Then it runs the `npm start` command and waits for a specific output before allowing the next command to run. This is only necessary for tasks that we need to keep alive. When the next command `npm run e2e` finishes, we know that the process has executed successfully.
## Why is proofreadme necessary?
It's not unusual for readme files to become stale, which makes it harder for new team members to get started on a project. By running proofreadme as a part of the ci process, there is some ability to reduce the likelihood of a stale readme file.
## CLI commands
### -h, --headers (required)
Select which headers in the readme you would like to run the code segments from.
Example:
````
# A Package
## Setup
```
npm install
```
## Advanced
```
npx package --init
```
## Tests
```
npm test
```
````
---
````
$ proofreadme -h "# A Package"
> npm install
> npx package --init
> npm test
````
````
$ proofreadme -h "## Setup" "## Tests"
> npm install
> npm test
````
### -p, --readme-path [path] (optional)
Provide the path to the readme file. (By default, will look for `README.md`, `readme.md`, and `Readme.md`)
````
$ proofreadme -p ./READ-ME.md
````
## @prm-directives
### @prm-ignore-x
Do not run the next x lines.
Example:
```
echo 1
# @prm-ignore-2
echo 2
echo 3
echo 4
```
Output:
```
> 1
> 4
```
### @prm-wait-until-regex-output-/x/
For the line that follows this directive, wait until the regex x matches the stdout before moving to the next command. This is useful when you want to run tests against another process, like a web server.
Example:
```
# @prm-wait-until-regex-output-/Accepting connections/
npx serve -p 3001
curl http://localhost:3000
```
Explanation:
The curl command only fires after the serve command outputs `Accepting connections`.
## Upcoming Features
- [ ] @prm-threads-x (Run commands in different threads)
- [ ] @prm-final-regex-output (When to exit long-running tasks)
- [ ] @prm-section-match-/x/-/y/-z (Use a double regex to ensure that your readme includes all of the regex matches of a particular file)
- [ ] @prm-file-folder-structure (Verifies that the project has the file-folder structure in the readme)
- [ ] @prm-multiline-x (Run multiple lines with a single command)
## Contributions
Contributions are welcome.