Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(README): Update README to describe new CLI parameters #31

Merged
merged 5 commits into from
Apr 13, 2021
Merged

docs(README): Update README to describe new CLI parameters #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4be9d5a
Update README, align yargs descriptions
dominique-mueller Apr 12, 2021
3be65d6
Improve CLI params table style
dominique-mueller Apr 12, 2021
565316a
Improve CLI params table style
dominique-mueller Apr 12, 2021
9c4e47b
Add emojis to README
dominique-mueller Apr 12, 2021
031e02f
Fix typos
dominique-mueller Apr 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 43 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,19 @@

## What it does

**[Hugo](https://gohugo.io/)** is one of the most popular static site generators. Now, when it comes to web development, we usually select
**[npm](https://www.npmjs.com/)** as our dependency management solution. **Hugo**, however, is a tool written in [Go](https://golang.org/).
Therefore, Hugo is not integrated into the npm module ecosystem - but instead delivered as a binary.
**[Hugo](https://gohugo.io/)** is one of the most popular static site generators. In the world of web development we usually choose
**[npm](https://www.npmjs.com/)** as our dependency management solution. **Hugo**, however, is written in [Go](https://golang.org/) - and
thus not integrated into the npm module ecosystem. Instead, users are asked to install Hugo globally on their systems. Suboptimal, really.

The **Hugo Installer** is here to help! It's a small node script which can be used to fetch a specific Hugo binary, for instance using the
`postinstall` hook within a `package.json` file.
But don't you worry, **Hugo Installer** is here to help! It's a small Node.js script which you can use to fetch the correct Hugo binary for
your system, e.g. via a `postinstall` hook within a `package.json` file. Neat!

Features include:

- :computer: Compatible with all operating systems and system architectures (Windows, MacOS, Linux, ..., CI/CD)
- :star: Supports all Hugo versions, including extended version
- :heart: Verifies checksum & runs health check when installing
- :eyes: Recognizes already downloaded binaries

<br><br><br>

Expand All @@ -30,13 +37,13 @@ npm install hugo-installer --save-dev

### Requirements

- **hugo-installer** requires **NodeJS 10** (or higher) to be installed
- **hugo-installer** requires **NodeJS 12** (or higher) to be installed

<br><br><br>

## How to use

We recommended to use the **hugo-installer** within the `postinstall` hook of a project's `package.json` file.
We recommended to use **hugo-installer** as part of your `postinstall` hook within your project's `package.json` file.

<br>

Expand All @@ -47,12 +54,15 @@ The Hugo version can be set using the `--version` CLI parameter. For example:
```json
{
"scripts": {
"postinstall": "hugo-installer --version 0.46"
"postinstall": "hugo-installer --version 0.82.0"
}
}
```

You can also use the extended version of Hugo:
> Important: Make sure to use the exact version number as used in the
> [official Hugo GitHub releases](https://github.com/gohugoio/hugo/releases) (e.g. trailing zeros that exist or do not exist)

You can also use the extended version of Hugo (for some operating systems!) by specifying the `--extended` CLI parameter. For example:

```json
{
Expand All @@ -62,8 +72,8 @@ You can also use the extended version of Hugo:
}
```

Bonus tip: The `--version` CLI parameter can also be an object path to some value defined in the `package.json` file. This allows for the
hugo version to be configured someplace else, e.g. in a `otherDependencies` object:
**Bonus tip:** The `--version` CLI parameter can also be an object path to some value defined in your `package.json` file. This allows for the
Hugo version to be configured someplace else, e.g. in a `otherDependencies` object. For example:

```json
{
Expand All @@ -78,33 +88,40 @@ hugo version to be configured someplace else, e.g. in a `otherDependencies` obje

<br>

### Configure binary path (optional)
### Full list of CLI parameters

The `--destination` CLI parameter can be used to define the folder into which the Hugo binary will be placed. This parameter is optional,
the default destination path is `bin/hugo`. For example:
The following lists all available CLI parameters and their respective default values. Only the `--version` CLI parameter is required.

```json
{
"scripts": {
"postinstall": "hugo-installer --version 0.46 --destination bin/hugo"
}
}
```
| CLI parameter | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--arch [arch]` | System architecture that the binary will run on. It is recommended to<br>use auto-detect by not using this option.<br><br>→ Default value: Auto-configured on runtime using `os.arch()` |
| `--destination [path]` | Path to the folder into which the binary will be put. Make sure to add<br>this path to your `.gitignore` file.<br><br>→ Default value: `bin/hugo` |
| `--downloadUrl [url]` | Source base URL from where the Hugo binary will be fetched. By default,<br>GitHub will be used. When using a custom URL, make sure to replicate<br>GitHub release asset URLs and append a trailing slash to the custom URL.<br><br>→ Default value: `https://github.com/gohugoio/hugo/releases/download/` |
| `--extended` | Download the extended version of Hugo.<br><br>→ Default value: `false` |
| `--force` | Force clean install of Hugo, ignoring already installed / cached binaries.<br><br>→ Default value: `false` |
| `--os [os]` | Operating system that the binary should run on. It is recommended to<br>use auto-detect by not using this option. <br><br>→ Default value: Auto-configured on runtime using `os.platform()` |
| `--skipChecksumCheck` | Skip checksum checks for downloaded binaries. It is recommended to<br>leave this option enabled. <br><br>→ Default value: `true` |
| `--skipHealthCheck` | Skip health checks for downloaded binaries. It is recommended to leave<br>this option enabled. <br><br>→ Default value: `true` |
| `--version [version]` | Hugo version to install, or path to package.json entry with the version.<br>Make sure to use the exact version number as defined in the<br>[official Hugo GitHub releases](https://github.com/gohugoio/hugo/releases). |

> Don't forget to add the destination path to your `.gitignore` file!
You can always take a look at all available CLI parameters using the `--help` CLI parameter. For example:

```bash
hugo-installer --help
```

<br><br><br>

## Using the Hugo binary

Once fetched, the hugo binary can be used directly from your favourite command line. For example:
Once fetched, the hugo binary can be used directly from your favourite command line or as part of an npm script. For example:

```bash
bin/hugo/hugo.exe --config=hugo.config.json
bin/hugo/hugo --config=hugo.config.json
```

Alternatively, one might also want to integrate Hugo in a NodeJS build script, or a NodeJS-based build tool such as
**[Gulp](https://gulpjs.com/)**. You can execute the Hugo binary using the `spawn` command. For example:
One might also want to integrate Hugo in a NodeJS build script, or a NodeJS-based build tool such as **[Gulp](https://gulpjs.com/)**. You
can execute the Hugo binary using the Node.JS `spawn` function. For example:

```js
const path = require('path');
Expand Down
10 changes: 5 additions & 5 deletions bin/hugo-installer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ const argv = yargs(hideBin(process.argv))
.option('arch', {
choices: ['arm', 'arm64', 'x64', 'x86'],
default: os.arch(),
describe: 'System architecture that the binary should run on. It is recommended to use auto-detect by not using this option.',
describe: 'System architecture that the binary will run on. It is recommended to use auto-detect by not using this option.',
})
.option('destination', {
default: 'bin/hugo',
describe: 'Destination to download the Hugo binary into.',
describe: 'Path to the folder into which the binary will be put. Make sure to add this path to your "gitignore" file.',
type: 'string',
})
.option('downloadUrl', {
Expand All @@ -34,12 +34,12 @@ const argv = yargs(hideBin(process.argv))
})
.option('extended', {
default: false,
describe: 'Download Hugo extended version.',
describe: 'Download the extended version of Hugo.',
type: 'boolean',
})
.option('force', {
default: false,
describe: 'Force clean install of Hugo, ignoring already installed / cached binaries',
describe: 'Force clean install of Hugo, ignoring already installed / cached binaries.',
type: 'boolean',
})
.option('os', {
Expand All @@ -59,7 +59,7 @@ const argv = yargs(hideBin(process.argv))
})
.option('version', {
describe:
'Hugo version to install, or path to package.json value with the version. Make sure to use the exact version number defined in Hugo releases.',
'Hugo version to install, or path to package.json entry with the version. Make sure to use the exact version number as defined in the official Hugo GitHub releases.',
type: 'string',
required: true,
})
Expand Down