osiolabs-copy editor

This repository contains a set of tools used for reviewing, and linting, Osio Labs content.

Usage

Note: You shouldn't use this project directly, rather, you should include it as a dependency for a content repo, and run the commands from within that repo. For details about adding this to a content repo see the installation section below.

Before you can use the tools you need to install all the dependencies:

Run npm install in the root directory of the content repo
Install Vale. https://vale.sh/docs/vale-cli/installation/

Tutorial linter (remark-lint)

The linter enforces Markdown and other objective formatting styles. Violating linter styles should be considered an error, and should be fixed before the content is published.

The linter consists of a configuration file for remark-cli, a custom remark plugin for handing Osio Labs specific tags like [# summary #]. And some instructions about how to use them.

Use the linter

npm run lint path/to/file.md: Lint an individual file.
npm run lint:all: Lint all files in the content repo.
npm run lint:fix path/to/file.md: Automate fixing as many linting errors in a file as possible. Note: this will not get all of them.

Tutorial review (Vale)

This set of rules is intended to provide recommendations for improving a tutorial's content. As well as checking for things like Drupal vs. drupal. Violating the copy review styles should be considered a warning not an error, and should at least be reviewed before the content is published. There are likely to be many exceptions to these rules.

For now we provide a set of vale rules that implement the Osio Labs style guide, and provide other copy editing recommendations. You'll need to install vale to use them.

Use the review tools

npm run review path/to/file.md: Output a Vale review for a specific file.
npm run review:all: Output a Vale review for all files in a content repo.

HTML exporter

The /to-html.js script can be used to export tutorial markdown files to HTML. It is currently intended used to export Drupalize.Me content for use on Thinkific.

Example:

npm run export-html path/to/file.md

It can convert most of our special tags like [# summary #] and [# steps #] to HTML. And handles transforming links and video embeds for Thinkific.

When a tutorial links to another .md file in the same repository this will open the .md file that the link points to and look for a thinkific URL tag in the linked tutorial. If it finds one, then it will replace the link in the original tutorial with Thinkific link. If a thinkific link can not be found then the anchor tag is stripped from the link and a warning is output.

Example thinkific URL tag:

<!-- thinkific-url:https://example.com/thinkific-thing -->

If a tutorial .md file contains a video embed like:

[# video #]
id: 1235
title: Video title
[# endvideo #]

And a special block like the following anywhere in the .md file:

<!-- thinkific-video-embed -->
<p>EXAMPLE EMBED CODE STORED HERE</p>
<!-- /thinkific-video-embed -->

The content of the [# video #] tag will be replaced with the content of the  block.

Install copyeditor into a content repo

For most use-cases you'll want to add this as a dependency to whichever content repo you want to use the tools with. And then execute them using npm run.

Note: Using the review tools requires that you have vale installed. See below.

npm install https://github.com/OsioLabs/osiolabs-copyeditor

Then add something like the following to your projects package.json file:

"scripts": {
  "lint": "remark --rc-path=./node_modules/osiolabs-copyeditor/.remarkrc.yml",
  "lint:all": "remark --rc-path=./node_modules/osiolabs-copyeditor/.remarkrc.yml content/",
  "lint:fix": "remark --output --rc-path=./node_modules/osiolabs-copyeditor/.remarkrc.yml",
  "review": "vale --config='./node_modules/osiolabs-copyeditor/.vale.ini'",
  "review:all": "npm run review content/"
},

Modifying rules

You can read more about adding or modifying the existing Vale rules here: https://vale.sh/docs/topics/styles/

OsioLabs / osiolabs-copyeditor

readme