From 3d2e84a7fb467fe049a4ed26ab44d9ca268d9585 Mon Sep 17 00:00:00 2001 From: Romein van Buren Date: Mon, 24 May 2021 18:05:14 +0200 Subject: [PATCH] Upgrade documentation site --- README.md | 2 + docs/_config.yml | 2 + docs/_data/navigation.yml | 20 +++++ docs/about/alternatives.md | 29 +++++++ docs/about/why.md | 44 +++++++++++ docs/api/supported-alphabets.md | 17 +++++ docs/index.md | 131 ++------------------------------ docs/usage/advanced.md | 17 +++++ docs/usage/installation.md | 21 +++++ docs/usage/usage.md | 18 +++++ 10 files changed, 176 insertions(+), 125 deletions(-) create mode 100644 docs/about/alternatives.md create mode 100644 docs/about/why.md create mode 100644 docs/api/supported-alphabets.md create mode 100644 docs/usage/advanced.md create mode 100644 docs/usage/installation.md create mode 100644 docs/usage/usage.md diff --git a/README.md b/README.md index c637ad4..fe6a985 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ [![CI](https://github.com/garraflavatra/alphabets/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/garraflavatra/alphabets/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/alphabets)](https://www.npmjs.com/package/alphabets) [![npm bundle size](https://img.shields.io/bundlephobia/min/alphabets)](https://www.npmjs.com/package/alphabets) +[![GitHub last commit](https://img.shields.io/github/last-commit/garraflavatra/alphabets)](https://github.com/garraflavatra/alphabets) +[![Forum](https://img.shields.io/badge/-forum-blue)](https://github.com/garraflavatra/alphabets) A tiny JS dependency (<2kb!) which exports many alphabets for many use diff --git a/docs/_config.yml b/docs/_config.yml index 8ae28ee..1332e3e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -35,4 +35,6 @@ defaults: values: layout: single toc: true + sidebar: + nav: "docs" \ No newline at end of file diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml index 187a1ba..dccce6c 100644 --- a/docs/_data/navigation.yml +++ b/docs/_data/navigation.yml @@ -3,3 +3,23 @@ main: url: https://github.com/garraflavatra/alphabets/discussions - title: "GitHub" url: https://github.com/garraflavatra/alphabets + +docs: + - title: About + children: + - title: Why would I use this? + url: /about/why + - title: Alternatives + url: /about/alternatives + - title: Usage + children: + - title: Installation + url: /usage/installation + - title: Usage + url: /usage/usage + - title: Advanced + url: /usage/advanced + - title: API + children: + - title: Supported alphabets + url: /api/supported-alphabets diff --git a/docs/about/alternatives.md b/docs/about/alternatives.md new file mode 100644 index 0000000..18c9169 --- /dev/null +++ b/docs/about/alternatives.md @@ -0,0 +1,29 @@ +--- +title: Alternatives to Alphabets +--- + +Know more alternatives? Please open an +[issue](https://github.com/garraflavatra/alphabet.js/issues/new) or +[pull request](https://github.com/garraflavatra/alphabet.js)! +{: .notice--info} + +## [alphabet](https://www.npmjs.com/package/alphabet) + +(whithout trailing `s`) + +I do not say this package doesn't work. I think it will work perfectly, but it +has less features: +{: .notice--warning} + +Seems a good alternative, right? But: + +* It only supports the Latin alphabet. +* It is larger. (The size is equal to this package's size, but this package + includes more.) +* It is only [CommonJS](https://en.wikipedia.org/wiki/CommonJS) and not + [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript) etc. +* When did the author last update it? Right. +
+ Last updated: 6 years ago +
Hmmm...
+
diff --git a/docs/about/why.md b/docs/about/why.md new file mode 100644 index 0000000..fb7bdc9 --- /dev/null +++ b/docs/about/why.md @@ -0,0 +1,44 @@ +--- +title: Why would I use this? +--- + +I have seen developers doing this: + +```js +const alphabet = 'abcdefghijklmnopqrstuvwxyz'.split(''); +``` + +Or worse: + +```js +const alphabet = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"]; +``` + +My opinion about this? 🙄. It's ugly, it makes your code less readable +(read: ugly) and it's simply not something you should want to have in your +code! Instead, you should do it like so: + +```js +import { latin } from 'alphabets'; +// or +const alphabets = require('alphabets'); +``` + +Much cleaner, right? That's why I made this package. + +## Why not? + +I see very few reasons not to use this package. + +### But doesn't it cost me performance? + +No. This package is only <800 bytes so it should not cost you any performance. +Neither via [CDN](/usage/installation/#cdn) nor if you use a bundler like +webpack, Parcel or Rollup. + +### Why not making an array on my own? + +It's a choice. This whole package is **opinionated**. *I* think you should not +do `const alphabet = 'abcdefghijklmnopqrstuvwxyz'.split('');` in your code. *I* +think you should use a package for that. Do you think it's OK to define your own +alphabet array? Do that! diff --git a/docs/api/supported-alphabets.md b/docs/api/supported-alphabets.md new file mode 100644 index 0000000..842db1d --- /dev/null +++ b/docs/api/supported-alphabets.md @@ -0,0 +1,17 @@ +--- +title: Supported alphabets +toc: false +--- + +Usage: see [Usage](#usage). + +| Name | Export name | +|------|-------------| +| Danish | `danish` | +| Faroese | `faroese` | +| Greek (modern) | `greek` | +| Greek (ancient/polytonic) | `greekPolytonic` | +| Icelandic | `icelandic` | +| Latin | `latin` | +| Norwegian | `norwegian` | +| Swedish | `swedish` | diff --git a/docs/index.md b/docs/index.md index 55c8811..513dd98 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,135 +1,16 @@ --- title: Alphabets +toc: false --- -A tiny JS dependency (<2kb!) which exports many alphabets for many use +A tiny JS dependency (<2kb!) which exports many alphabet arrays for many use cases. [![CI](https://github.com/garraflavatra/alphabets/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/garraflavatra/alphabets/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/alphabets)](https://www.npmjs.com/package/alphabets) [![npm bundle size](https://img.shields.io/bundlephobia/min/alphabets)](https://www.npmjs.com/package/alphabets) +[![GitHub last commit](https://img.shields.io/github/last-commit/garraflavatra/alphabets)](https://github.com/garraflavatra/alphabets) +[![Forum](https://img.shields.io/badge/-forum-blue)](https://github.com/garraflavatra/alphabets) -## Why would I use this? - -### Why? - -I have seen developers doing this: - -```js -const alphabet = 'abcdefghijklmnopqrstuvwxyz'.split(''); -``` - -Or worse: - -```js -const alphabet = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"]; -``` - -My opinion about this? 🙄. It's ugly, it makes your code less readable -(read: ugly) and it's simply not something you should want to have in your -code! Instead, you should do it like so: - -```js -import { latin } from 'alphabets'; -// or -const alphabets = require('alphabets'); -``` - -Much cleaner, right? That's why I made this package. - -### Why not? - -I see very few reasons not to use this package. - -#### But doesn't it cost me performance? - -No. This package is only <800 bytes so it should not cost you any performance. -Neither via CDN nor if you use a bundler like webpack, Parcel or Rollup. - -#### Why not making an array on my own? - -It's a choice. This whole package is **opinionated**. *I* think you should not -do `const alphabet = 'abcdefghijklmnopqrstuvwxyz'.split('');` in your code. *I* -think you should use a package for that. Do you think it's OK to define your own -alphabet array? Do that! - -### Competitors - -Know more alternatives? Please open an -[issue](https://github.com/garraflavatra/alphabet.js/issues/new) or -[pull request](https://github.com/garraflavatra/alphabet.js)! -{: .notice--info} - -#### [alphabet](https://www.npmjs.com/package/alphabet) - -Seems a good alternative, right? But: - -* It only supports the Latin alphabet. -* It is larger. (The size is equal to this package's size, but this package - includes more.) -* It is only [CommonJS](https://en.wikipedia.org/wiki/CommonJS) and not - [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript) etc. -* When did the author last update it? Right. -
- Last updated: 6 years ago -
Hmmm...
-
- -I do not say this package doesn't work. I think it will work perfectly, but it -has less features. -{: .notice--warning} - -## Usage - -### Installation - -Use npm: - -```bash -npm install alphabets --save -``` - -Or if you prefer Yarn: - -```bash -yarn add alphabets -``` - -CDN, if that's more your style: - -```html - -``` - -### Usage - -```js -import { } from 'alphabets'; -``` - -or: - -```js -const alphabets = require('alphabets'); -console.log(alphabets.); -``` - -where `` is an alphabet this package supports. -[Here](#supported-alphabets) is a list from which you can choose. - -## API - -### Supported alphabets - -Usage: see [Usage](#usage). - -| Name | Export name | -|------|-------------| -| Danish | `danish` | -| Faroese | `faroese` | -| Greek (modern) | `greek` | -| Greek (ancient/polytonic) | `greekPolytonic` | -| Icelandic | `icelandic` | -| Latin | `latin` | -| Norwegian | `norwegian` | -| Swedish | `swedish` | +Are you convinced [why to use this](/about/why)? Get started +[here](/usage/installation)! diff --git a/docs/usage/advanced.md b/docs/usage/advanced.md new file mode 100644 index 0000000..c1680a0 --- /dev/null +++ b/docs/usage/advanced.md @@ -0,0 +1,17 @@ +--- +title: Advanced usage +--- + +## Alphabet as a string + +```js +alphabet.join('')[0]; +//=> 'abcdefghijklmnopqrstuvwxyz' +``` + +## Uppercase + +```js +alphabet.toUpperCase(); +//=> ["Α", "Β", "Γ", "Δ", "Ε", "Ζ", "Η", "Θ", "Ι", "Κ", "Λ", "Μ", "Ν", "Ξ", "Ο", "Π", "Ρ", "Σ", "Τ", "Υ", "Φ", "Χ", "Ψ", "Ω"] +``` diff --git a/docs/usage/installation.md b/docs/usage/installation.md new file mode 100644 index 0000000..0b81486 --- /dev/null +++ b/docs/usage/installation.md @@ -0,0 +1,21 @@ +--- +title: Installation +--- + +## npm + +```bash +npm install alphabets --save +``` + +## Yarn + +```bash +yarn add alphabets +``` + +## CDN + +```html + +``` diff --git a/docs/usage/usage.md b/docs/usage/usage.md new file mode 100644 index 0000000..792284a --- /dev/null +++ b/docs/usage/usage.md @@ -0,0 +1,18 @@ +--- +title: Usage +toc: false +--- + +```js +import { } from 'alphabets'; +``` + +or: + +```js +const alphabets = require('alphabets'); +console.log(alphabets.); +``` + +where `` is an alphabet this package supports. +[Here](/api/supported-alphabets) is a list from which you can choose.