Ensure all documentation is formatted the same way #36
Comments
|
Discussed offline earlier with @mcleo-d about making this contribution and he's in agreement to give it a whirl. |
|
The rest of FINOS uses Docusaurus for this sort of thing (the presentation layer, at least). It may make sense to be consistent and use that tool. |
|
Also, it's probably not a good idea to require use of specific tools (VS Code). Many of the contributors are unlikely to be familiar with developer tools like this. |
|
@vmbrasseur thanks for the details, I also heard from @mcleo-d that Docusaurus is popular in the FINOS community, so glad to reuse existing tooling 😄. I wasn't thinking to require VS Code, however, with #37 it is what GitHub CodeSpaces is built on so it hopefully won't be a hurdle. That said, the Markdown All In One plugin isn't required per say, it just generates the initial Table of Contents and theoretically it can be kept up to date manually. However, looking into it further, it seems that in April 2021 GitHub released a feature that automatically adds a TOC, so maybe this isn't even necessary. |
In order to have Prettier for formatting all the Markdown files, we need to add a package.json for npm. re #36
Add a dependency on the Prettier package so we can start using it for formatting Markdown files. Add the package-lock.json to ensure we maintain our dependency tree in source control. Also, we now need to ensure we gitignore the node_modules directory. re #36
Using NPM's scripts feature, add a couple useful commands to format the markdown files and ensure they stay formatted. re #36
Now that we have prettier installed and easy to access npm scripts, we can format all the Markdown files to the default Prettier formatting. re #36
Add clear instructions to ensure all contributions format documents with Prettier and add an initial section outlining how to setup one's workstation for making a contribution. re #36
Make sure the Markdown documents stay consistently formatted by failing the build if the `npm lint` (i.e. Prettier's check command) execute successfully. fix #36
In order to have Prettier for formatting all the Markdown files, we need to add a package.json for npm. re #36
Add a dependency on the Prettier package so we can start using it for formatting Markdown files. Add the package-lock.json to ensure we maintain our dependency tree in source control. Also, we now need to ensure we gitignore the node_modules directory. re #36
Using NPM's scripts feature, add a couple useful commands to format the markdown files and ensure they stay formatted. re #36
Now that we have prettier installed and easy to access npm scripts, we can format all the Markdown files to the default Prettier formatting. re #36
Add clear instructions to ensure all contributions format documents with Prettier and add an initial section outlining how to setup one's workstation for making a contribution. re #36
Make sure the Markdown documents stay consistently formatted by failing the build if the `npm lint` (i.e. Prettier's check command) execute successfully. fix #36
Make sure the Markdown documents stay consistently formatted by failing the build if the `npm lint` (i.e. Prettier's check command) execute successfully. fix #36
Feature Request
Description of Problem:
This repository mostly contains documentation, most of which is formatted in Markdown. It'd be great if we had a consistent way of formatting the Markdown documents and also making sure they conform with the
markdownlintlinter and it's clear for everyone how the documents should look. Furthermore, for longer docs it'd be good to have a Table of Contents to make it easier to navigate.Potential Solutions:
The Prettier project is a great way to format Markdown docs in one consistent format and ensures it follows markdownlint.
Furthermore, we should consider having up to date table of contents in longer pages. We could use the VS Code Markdown All In One plugin to generate the initial table of contents and keep it up to date.
The text was updated successfully, but these errors were encountered: