Docs

[vweevers]

Trying out some things, don't merge yet. Running npm run remark will regenerate the contributors section in the README.

@ralphtheninja

[ralphtheninja]

Love it!

[vweevers]

Remaining concerns:

1. You need a GitHub token to update contributors (but I made remark-gh-contributors a noop if no token is provided). I also tried getting contributors from git, but found that some people changed their email address, which meant it couldn't be matched with metadata from level-community.
2. remark-gh-contributors has no unit tests yet
3. We need to update level-community
4. The license (as well the License section in the readme) states that copyright belongs to Max Ogden "and Contributors", but we only list the top 10 contributors in the readme. Problem?
5. We should later move the remark stuff into hallmark, for configuration-less reuse.
6. Remark's default formatting isn't 100% compatible with our current style. While we could override remark's defaults, I don't think that we should. Sticking to defaults ensures compatibility with other tooling, and avoids bikeshedding on our part.

[ralphtheninja]

1. We can live with this for now. Maybe create issue for improving/simplifying/automating this?
2. Nice to have obviously, but no biggie for now
3. Create issue on what we need to update (I know README style etc)
4. For me personally, not a problem. Would be nice with a complete list though.
5. Create issue
6. 👍

[vweevers]

Regarding 4: one thing we can do is render a complete list into CONTRIBUTORS.md. All we need to do is create that file and change the npm script to remark README.md CONTRIBUTORS.md -o.

[vweevers]

And when we have a CONTRIBUTORS.md, we can link to it from LICENSE.md :)

[ralphtheninja]

@vweevers Now we're getting somewhere. Looks really nice!

[ralphtheninja]

How does remark know how each file should be processed and which plugin to apply to which output? CONTRIBUTORS.md is completely generated, right? Just curious about the algorithm of this command, in which order things are done etc.

[vweevers]

It's pretty much the same as doing remark README.md && remark CONTRIBUTORS.md. It'll use the same configuration, same list of plugins, but it creates a new processor (and plugin "instances") for each file.

[vweevers]

If you're wondering why remark-git-contributors doesn't modify README.md: because README.md doesn't have a # Contributors heading.

[ralphtheninja]

Aah ok. So I guess this means CONTRIBUTORS.md has to exist and have an empty # Contributors section at the very least.

[ralphtheninja]

@vweevers I'm guessing we are going to need our own custom tool, e.g. level-remark (or similar), that works sort of like what standard does. Since we most likely want to do the same operations in each repository, e.g. format README.md and create COLLABORATORS.md we will end up with the same setup in every single package.json.

[vweevers]

I'm guessing we are going to need our own custom tool, e.g. level-remark (or similar), that works sort of like what standard does. Since we most likely want to do the same operations in each repository, e.g. format README.md and create COLLABORATORS.md we will end up with the same setup in every single package.json.

That's where I was going with hallmark! :)

[ralphtheninja]

We also want to use remark for CHANGELOG.md, to get references and github user names correct.

[ralphtheninja]

That's where I was going with hallmark! :)

Aaaaaah! Now it makes even more sense 💡