readme-manager

helps manage and harmonise READMEs in many repositories with template files available on deno.land/x/readme_manager

Define a template directory and write a README template for your project then compile it into a proper README.

Installation

$ deno install --name readme-manager --reload --allow-all https://deno.land/x/readme_manager/cli.ts

Usage

On the first run without any arguments a setup will happen :

• match corresponds to the name the README template will have inside the repository it is created on first start but you can always recreate it with --setup (default .README.template.md)
• templates corresponds to the path where the rendering function is stored it is boostrapped on first start but you can always access it with --bootstrap (default $USER_CONFIG_DIR/readme-manager)

$ readme-manager
# Will guide you through setup on first run

$ readme-manager
# Will create readme in current directory with template and config

$ readme-manager my-project
# Will create readme in my-project directory with template and config

$ readme-manager [...] --templates [path]
# Will create a readme with config match and overriden template directory

$ readme-manager [...] --match [name]
# Will create a readme with config template directory and overriden match name

$ readme-manager [...] --templates [path] --match [name]
# Will create a readme and bypass configuration (if it exists)

There are also some other commands :

$ readme-manager --help
# Will print the help page

$ readme-manager --setup
# Re-run setup step and backup old config

$ readme-manager --bootstrap
# Re-run templates boostrapping step and backup old directory

There is also a debug flag available that can be added to any command :

$ readme-manager [...] --debug
# Will print more information to console and save all logs to the log file (instead of only errors by default)

Example

You can check out the current templates I use for my project (including this readme) over here.

Templating

When you bootstrap the templates forlder, 3 examples files will be create for you :

• README.template.md: this is the base file that gets used when rendering your readme. You can await stuff in it. This is the only required file
• HEADER.template.md: is an example header you might use
• FOOTER.template.md: is an example footer you might use

Feel free to adjust, remove or add any files you might want. Simply keep in mind that README.template.md is required and will be the base for rendering.

Any file in the templates folder will be automatically required and available by its filename with await include(filename).

Any file that starts with . will be ignored.

Template variables

The following variables are available to the template (on it):

• name: basename of the folder the README is in
• readme: content of the readme template file
• readmeFilePath: the absolute filepath of the readme
• readmeDirectoryPath: the absolute path of the directory containing the readme
• gitTag: the current git tag
• gitURL: the repository url
• gitCommit: the sha of the current commit
• gitBranch: the current checkout out branch

You can use javascript inside the templates and also async templates for data fetching (see Eta docs)

Make sure to await any includes you do ! As templates are compiled in async mode for await support (even if you are not using it).

Templating docs

The templating engine use is https://deno.land/x/eta@v1.12.3.

More information about it can be found on their documentation.

Suggestion

If you are going to be using this for many repositories you might want tot setup a git template folder and add a precommit hook that runs the readme-manager.

Here is what mine looks like:

# ~/.git-templates/hooks/pre-commit
# git config --global init.templatedir '~/.git-templates'
# git init 

#!/usr/bin/env bash
~/.deno/bin/readme-manager
git add -u

Documentation

Documentation view is currently disabled for third party modules on deno.land/x but you can still view the auto generated docs on doc.deno.land

License

Most all of my work is now licensed under a modified CC-BY-NC-SA 4.0 AFEdit plus accounting for states existing in our world on top of capitalism.

This is a weird choice for code right?

Here are a few key reasons:

• my definition of "open" involves being able to share and modify, you are able to do such things, just not make money off of it, or oppress people
• my definition of "free" involves being able to share and modify, you are able to do such things, not just make money off of it, or oppressing people

So no, amongst other things, this list is not exhaustive,

• you cannot have somebody work on my tool and redistribute it to your employees
• you cannot resell copies of this because in this age distribution is not done with floppy disks and the internet is a thing
• you cannot use it to generate revenue yourself
• you cannot use it to "generate value" in a capitalistic sense
• you cannot use it in any military capacity
• you cannot use it in any law enforcement capacity
• you cannot use it in any state backed capacity
• you cannot use it in any surveillance capacity
• you cannot use it if you represent the interests of a state
• you cannot use it to oppress, spy, control in any capacity
• you cannot use it to injure, harm, kill, whether physically or psychologically

You can, however,

• change it to do whatever you please
• share it to anyone you please with attribution and under the same license
• use it as much as you please
• and probably a bunch of other cool things that are possible outside of a capitalistic, imperialistic frame of reference that permeates the tech scene

Most of the "arguments" for how "free" and "open" source licenses are done still to this day stem from archaic concepts that might not even be relevant these days and I fail to see the issue with this license not being "interoperable" with a bunch of what I deem to be "bad" licenses, as they all allow for commercial usage.

I also will not make any attempts to monetize these works and will at most ever offer the possibility to donate to me directly if you enjoy what I do.

Thank you that is all.

Development

To clone the repository locally:

$ git clone https://code.juke.fr/kay/readme-manager.git

Contributing

More to come later.

Issues

Open new issues by mailing eutychia.gitlab+readme-manager-issue@gmail.com

---

beep boop