<div><img alt="Logo" src="https://raw.githubusercontent.com/wessberg/sandhog/master/documentation/asset/logo.png" height="200" /></div>

A virtual Open Source project maintainer

Description

Sandhog is a tool that makes it easy for you to have a welcoming, professional-looking Github repository. It helps you generate and continuously maintain your README.md, LICENSE.md, CONTRIBUTING.md, FUNDING.yml, and CODE_OF_CONDUCT.md files by looking at the files inside your repository. This README is generated by Sandhog.

Features

Sandhog works out of the box without any configuration. Some highlights include:

Generation of relevant badges for your README
Generating of maintainer tables, including avatars, social links, and contact details
Generation of Patreon and Open Collective backer/sponsor images that doesn't require any maintenance
Generation of LICENSE.md files for a large variety of popular licenses.
Generation of CODE_OF_CONDUCT.md files
Generation of CONTRIBUTING.md files.
Generation of FUNDING.yml files

<div><img alt="Feature image" src="https://raw.githubusercontent.com/wessberg/sandhog/master/documentation/asset/feature.svg" height="300" /></div><br>

Backers

Patreon

Description
- Features
Backers
- Patreon
Table of Contents
Install
- npm
- Yarn
- pnpm
- Run once with npx
Engine
Usage
Contributing
- FAQ
  - Do you support custom templates?
  - How do you determine the Code Style of the project?
License

Install

npm

$ npm install sandhog --save-dev

Yarn

$ yarn add sandhog --dev

pnpm

$ pnpm add sandhog --save-dev

Run once with npx

$ npx sandhog

Engine

Sandhog requires Node.js v14.19.0 or newer to work correctly.

Usage

Configuration

Sandhog is highly configurable. You can provide a configuration in a variety of ways:

As a sandhog property inside your package.json file.
As a sandhog.config.js file within your repository root
As a sandhog.config.cjs file within your repository root
As a sandhog.config.mjs file within your repository root
As a sandhog.config.json file within your repository root
As a sandhog.config.json5 file within your repository root
As a sandhog.config.yaml file within your repository root
As a sandhog.config.yml file within your repository root
As a .sandhogrc (JSON-formatted) file within your repository root

Configuration options

interface SandhogOptions {
  // If true, the install directions inside generated READMEs will suggest installing this package as a development dependency.
  isDevelopmentPackage: boolean;
  // If provided, a logo image will be placed in the top of generated or updated README files
  logo: {
    // An URL to the logo.
    url: string;
    // The height of the logo in pixels
    height: number;
  };

  // If provided, a feature image will be placed within generated or updated README files
  featureImage: {
    // An URL to the feature image.
    url: string;
    // The height of the feature image in pixels
    height: number;
  };
  // If Patreon, Open Collective, and/or other donation options is given, badges and backer/sponsor shields will be generated and added to generated or updated README files.
  donate: {
    patreon: {
      userId: string;
    };
    openCollective: {
      project: string;
    };
    other: {
      fundingUrl: string;
      donors: [
        {
          name: string;
          url: string;
          imageUrl: string;
          twitter: string;
        }
      ];
    };
  };
  readme: {
    badges: {
      // The given iterable of SectionKinds will never be added to generated or updated READMEs
      // Can be any of the following: 'toc', 'logo', 'badges', 'description_short', 'description_long', 'features', 'feature_image', 'usage', 'install', 'contributing', 'maintainers', 'faq', 'backers', and 'license'
      exclude: Iterable<
        | "toc"
        | "logo"
        | "badges"
        | "description_short"
        | "description_long"
        | "features"
        | "feature_image"
        | "usage"
        | "install"
        | "contributing"
        | "maintainers"
        | "faq"
        | "backers"
        | "license"
      >;
    };
    sections: {
      // The given iterable of BadgeKinds will never be added to generated or updated READMEs.
      // Can be any of the following: 'downloads', 'dependencies', 'npm', 'contributors', 'license', 'patreon', 'open_collective_donate', 'open_collective_backers', 'open_collective_sponsors', and 'code_style'
      exclude: Iterable<
        | "downloads"
        | "dependencies"
        | "npm"
        | "contributors"
        | "license"
        | "patreon"
        | "open_collective_donate"
        | "open_collective_backers"
        | "open_collective_sponsors"
        | "code_style"
      >;
    };
  };
  // By default, Sandhog will try to locate a Prettier config within the project. You can also just provide it or override the Prettier options here
  prettier: PrettierOptions;
}

Additional metadata for `package.json` fields

Beyond the Sandhog configuration, Sandhog will look for metadata inside your package.json and use it to further enhance the files that can be produced by Sandhog. For example, the author and/or contributors properties of your package.json can include additional keys such as the individual contributors imageUrl, twitter handle, and github username.

For example:

// Inside package.json
{
  contributors: [
    {
      name: "John Done",
      email: "john@doe.com",
      url: "https://john.doe",

      // The following three fields are enhancements
      imageUrl: "https://john.doe/avatar.png",
      role: "Lead Developer",
      twitter: "JohnDoe",
      github: "johndoe"
    }
  ]
}

As seen in the code example above, contributors can be extended with the following optional properties:

| Property | Description | | ---------- | ------------------------------------------------------------------------------------------ | | imageUrl | An avatar that should be displayed above the rest of the information about the contributor | | role | The role of the contributor within the project. | | twitter | The Twitter handle for the contributor | | github | The Github username for the contributor

Sandhog

Install / Use

README