aboviq/emigrate
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: make all links relative to support mounting anywhere

Browse source
This commit is contained in:
Joakim Carlstein 2023-12-18 16:25:14 +01:00
parent 3bffb98750
commit 03ec8f2599
20 changed files with 59 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/package.json
View file

@ -22,6 +22,6 @@
"tailwindcss": "^3.3.6"
},
"volta": {
"extends": "../../package.json"
"extends": "../package.json"
}
}

2
docs/src/content/docs/commands/list.mdx
View file

@ -51,7 +51,7 @@ The directory where the migration files are located. The given path should be ab
### `-s`, `--storage <name>`
The storage to use for where to read the migration history.
The [storage plugin](../../plugins/storage/) to use, which is responsible for where to store the migration history.
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

4
docs/src/content/docs/commands/new.mdx
View file

@ -7,7 +7,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
The `new` command is used to create a new migration file in the given directory.
The migration file can be based on a template, generated by a [generator plugin](/plugins/generators/), or just be an empty file.
The migration file can be based on a template, generated by a [generator plugin](../../plugins/generators/), or just be an empty file.
## Usage
@ -69,7 +69,7 @@ The extension to use for the migration file. Unless the [`--template`](#t---temp
### `-p`, `--plugin <name>`
The [generator plugin](/plugins/generators/) to use. The generator plugin is responsible for generating the migration filename and its contents.
The [generator plugin](../../plugins/generators/) to use. The generator plugin is responsible for generating the migration filename and its contents.
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

2
docs/src/content/docs/commands/remove.mdx
View file

@ -58,7 +58,7 @@ Force removal of the migration history entry even if the migration file does not
### `-s`, `--storage <name>`
The storage to use for where to read the migration history.
The [storage plugin](../../plugins/storage/) to use, which is responsible for where to store the migration history.
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

4
docs/src/content/docs/commands/up.mdx
View file

@ -57,7 +57,7 @@ The directory where the migration files are located. The given path should be ab
### `-s`, `--storage <name>`
The storage to use for where to store the migration history.
The [storage plugin](../../plugins/storage/) to use, which is responsible for where to store the migration history.
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
@ -73,7 +73,7 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install
### `-p`, `--plugin <name>`
The [loader plugin(s)](/plugins/loaders/) to use. Can be specified multiple times to use multiple plugins.
The [loader plugin(s)](../../plugins/loaders/) to use. Can be specified multiple times to use multiple plugins.
The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

4
docs/src/content/docs/index.mdx
View file

@ -29,10 +29,10 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
Migrate many databases from one repository or many repositories to one database. There's no need to synchronize deployments.
</Card>
<Card title="SQL, JavaScript, TypeScript, etc." icon="document">
Write your migration files using the [language of your choice](/plugins/loaders/).
Write your migration files using the [language of your choice](plugins/loaders/).
And mix and match them as you need. E.g. `SQL` for database schema changes, and `JavaScript` for data transformation.
</Card>
<Card title="Customize to your setup" icon="puzzle">
Emigrate is designed to be flexible and customizable to suite any environment and setup using its [plugin system](/plugins/).
Emigrate is designed to be flexible and customizable to suite any environment and setup using its [plugin system](plugins/).
</Card>
</CardGrid>

12
docs/src/content/docs/intro/quick-start.mdx
View file

@ -11,7 +11,7 @@ But for now, this is the way to go.
:::
<LinkCard
href="/intro/whats-emigrate/"
href="../whats-emigrate/"
title="What's Emigrate?"
description="Learn more about Emigrate and what it can do for you."
/>
@ -38,7 +38,7 @@ But for now, this is the way to go.
### Pick a storage plugin
Emigrate uses a [storage plugin](/plugins/storage/) to store the migration history.
Emigrate uses a [storage plugin](../plugins/storage/) to store the migration history.
Install the plugin you want to use, for example:
@ -84,7 +84,7 @@ Otherwise the file would have the `.js` extension by default.
:::tip[Did you know?]
You can avoid typing `--plugin mysql` by configuring Emigrate using an `emigrate.config.js` file.
See [Configuration](/configuration/) for more information.
See [Configuration](../reference/configuration/) for more information.
:::
#### Fill the migration file
@ -132,7 +132,7 @@ npx emigrate up --storage mysql --plugin mysql --dry
```
:::note
This will connect to the database using some default values. For ways to configure the connection, see [Configuration](/configuration).
This will connect to the database using some default values. For ways to configure the connection, see [Configuration](../reference/configuration/).
:::
:::caution
@ -141,6 +141,6 @@ Be sure to configure the connection correctly and use the `--dry` flag to test y
:::
:::tip[Did you know?]
In the example above the `@emigrate/mysql` plugin is used twice, once for the `--storage` option as a [Storage Plugin](/plugins/storage/)
and once for the `--plugin` option as a [Loader Plugin](/plugins/loaders/) to be able to read `.sql` files.
In the example above the `@emigrate/mysql` plugin is used twice, once for the `--storage` option as a [Storage Plugin](../plugins/storage/)
and once for the `--plugin` option as a [Loader Plugin](../plugins/loaders/) to be able to read `.sql` files.
:::

10
docs/src/content/docs/intro/whats-emigrate.mdx
View file

@ -7,11 +7,11 @@ Emigrate is written in [TypeScript](https://www.typescriptlang.org) and is a mig
* It's database agnostic - you can use it with any database, or even with non-database data.
* It's the successor of [klei-migrate](https://github.com/klei/migrate) and is designed to be compatible with [Immigration](https://github.com/blakeembrey/node-immigration) and many of its storage plugins, as well as [Migrate](https://github.com/tj/node-migrate).
* It supports migration files written using [CommonJS or ES Modules out of the box](/plugins/loaders/default/), with any of the following extensions: `.js`, `.cjs` or `.mjs`, and supports [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or using the [NodeJS Callback Pattern](https://nodejs.org/en/learn/asynchronous-work/javascript-asynchronous-programming-and-callbacks#handling-errors-in-callbacks).
* Other languages can be used by using a [Loader Plugin](/plugins/loaders/).
* The migration history can be stored anywhere using a [Storage Plugin](/plugins/storage/).
* The output can be customized using [Reporters](/plugins/reporters/).
* It supports migration files written using [CommonJS or ES Modules out of the box](../../plugins/loaders/default/), with any of the following extensions: `.js`, `.cjs` or `.mjs`, and supports [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or using the [NodeJS Callback Pattern](https://nodejs.org/en/learn/asynchronous-work/javascript-asynchronous-programming-and-callbacks#handling-errors-in-callbacks).
* Other languages can be used by using a [Loader Plugin](../../plugins/loaders/).
* The migration history can be stored anywhere using a [Storage Plugin](../../plugins/storage/).
* The output can be customized using [Reporters](../../plugins/reporters/).
:::tip[Did you know?]
Thanks to [the plugin system](/plugins/) you can even write migrations in plain SQL! So no need for Java-based tools like Liquibase or Flyway.
Thanks to [the plugin system](../../plugins/) you can even write migrations in plain SQL! So no need for Java-based tools like Liquibase or Flyway.
:::

8
docs/src/content/docs/plugins/generators/index.mdx
View file

@ -8,17 +8,17 @@ A generator plugin is a plugin that generates new migration files.
They are responsible for both generating the new file's name and its contents.
:::tip[Did you know?]
Many of the [Loader Plugins](/plugins/loaders/) usually include a generator plugin as well.
Many of the [Loader Plugins](../loaders/) usually include a generator plugin as well.
The generator is responsible for generating migration files in a specific format and the loader is responsible for loading the same format.
:::
## Available Generator Plugins
<CardGrid>
<LinkCard title="JavaScript generator" href="/plugins/generators/js/" description="A generator that generates .js migration files (using ESM and default export)" />
<LinkCard title="MySQL generator" href="/plugins/generators/mysql/" description="A generator that generates .sql migration files" />
<LinkCard title="JavaScript generator" href="js/" description="A generator that generates .js migration files (using ESM and default export)" />
<LinkCard title="MySQL generator" href="mysql/" description="A generator that generates .sql migration files" />
</CardGrid>
:::note
Instead of having to install a generator plugin, you can also use the much simpler [`--template`](/commands/new/#t---template-path) option to specify a custom template file for new migrations.
Instead of having to install a generator plugin, you can also use the much simpler [`--template`](../../commands/new/#t---template-path) option to specify a custom template file for new migrations.
:::

4
docs/src/content/docs/plugins/generators/js.mdx
View file

@ -4,7 +4,7 @@ title: "JavaScript Generator"
import { Tabs, TabItem } from '@astrojs/starlight/components';
A [generator plugin](/plugins/generators/) for generating new migration files in JavaScript.
A [generator plugin](../) for generating new migration files in JavaScript.
## Installation
@ -32,4 +32,4 @@ A [generator plugin](/plugins/generators/) for generating new migration files in
emigrate new --plugin generate-js create some fancy table
```
For more information see [the `new` command](/commands/new/)'s documentation.
For more information see [the `new` command](../../commands/new/)'s documentation.

4
docs/src/content/docs/plugins/generators/mysql.mdx
View file

@ -4,7 +4,7 @@ title: "MySQL Generator"
import { Tabs, TabItem } from '@astrojs/starlight/components';
The MySQL generator creates new migration files with the `.sql` extension. In the same package you can find the [MySQL Loader](/plugins/loaders/mysql/) and the [MySQL Storage](/plugins/storage/mysql/).
The MySQL generator creates new migration files with the `.sql` extension. In the same package you can find the [MySQL Loader](../../loaders/mysql/) and the [MySQL Storage](../../storage/mysql/).
## Installation
@ -32,4 +32,4 @@ The MySQL generator creates new migration files with the `.sql` extension. In th
emigrate new --plugin mysql create some fancy table
```
For more information see [the `new` command](/commands/new/)'s documentation.
For more information see [the `new` command](../../../commands/new/)'s documentation.

8
docs/src/content/docs/plugins/index.mdx
View file

@ -11,25 +11,25 @@ Emigrate uses a plugin system to allow you to extend and customize the functiona
Emigrate supports different types of plugins that all have different purposes.
<LinkCard
href="/plugins/storage/"
href="storage/"
title="Storage Plugins"
description="The most important plugin type. A storage plugin is responsible for storing and handling the migration history state."
/>
<LinkCard
href="/plugins/loaders/"
href="loaders/"
title="Loader Plugins"
description="A loader plugin is responsible for loading migration files with a specific format and transforming them into a JavaScript function."
/>
<LinkCard
href="/plugins/reporters/"
href="reporters/"
title="Reporters"
description="A reporter is responsible for the output of the migration process. Use a different reporter if you want the output suitable for log shipping or to be machine readable."
/>
<LinkCard
href="/plugins/generators/"
href="generators/"
title="Generator Plugins"
description="A generator plugin generates new migration files. Usually included in loader plugin packages so the same package can be used for both creating and loading migrations in a certain format."
/>

10
docs/src/content/docs/plugins/loaders/index.mdx
View file

@ -6,7 +6,7 @@ import { LinkCard, CardGrid } from '@astrojs/starlight/components';
Loader plugins are used to transform any file type into a JavaScript function that will be called when the migration file is executed.
Out of the box, Emigrate supports the following file extensions: `.js`, `.cjs` and `.mjs`. And both CommonJS and ES Modules are supported. See the [Default Loader](/loaders/default/) for more information.
Out of the box, Emigrate supports the following file extensions: `.js`, `.cjs` and `.mjs`. And both CommonJS and ES Modules are supported. See the [Default Loader](default/) for more information.
## Using a loader plugin
@ -16,17 +16,17 @@ You can specify a loader plugin via the `--plugin` (or `-p` for short) option:
npx emigrate up --plugin mysql
```
Or set it up in your configuration file, see [Plugin configuration](/reference/configuration/#plugins) for more information.
Or set it up in your configuration file, see [Plugin configuration](../../reference/configuration/#plugins) for more information.
:::tip[Did you know?]
You can specify multiple loader plugins at the same time, which is needed when you mix file types in your migrations folder.
For example, you can use the `mysql` loader for `.sql` files and the `typescript` loader for `.ts` files.
The [default loader](/plugins/loaders/default/) will be used for all other file types, and doesn't need to be specified.
The [default loader](default/) will be used for all other file types, and doesn't need to be specified.
:::
## Available Loader Plugins
<CardGrid>
<LinkCard title="Default Loader" href="/plugins/loaders/default/" description="The loader responsible for loading .js, .cjs and .mjs files" />
<LinkCard title="MySQL Loader" href="/plugins/loaders/mysql/" description="Can load and execute .sql files against a MySQL database" />
<LinkCard title="Default Loader" href="default/" description="The loader responsible for loading .js, .cjs and .mjs files" />
<LinkCard title="MySQL Loader" href="mysql/" description="Can load and execute .sql files against a MySQL database" />
</CardGrid>

6
docs/src/content/docs/plugins/loaders/mysql.mdx
View file

@ -4,7 +4,7 @@ title: MySQL Loader Plugin
import { Tabs, TabItem } from '@astrojs/starlight/components';
The MySQL loader plugin transforms `.sql` files into JavaScript functions that Emigrate can use to execute the migrations. In the same package you can find the [MySQL Generator](/plugins/generators/mysql/) and the [MySQL Storage](/plugins/storage/mysql/).
The MySQL loader plugin transforms `.sql` files into JavaScript functions that Emigrate can use to execute the migrations. In the same package you can find the [MySQL Generator](../../generators/mysql/) and the [MySQL Storage](../../storage/mysql/).
## Installation
@ -28,7 +28,7 @@ The MySQL loader plugin transforms `.sql` files into JavaScript functions that E
## Configuration
The MySQL loader plugin can be configured either using environment variables or by configuring the plugin directly in the [`emigrate.config.js` file](/reference/configuration).
The MySQL loader plugin can be configured either using environment variables or by configuring the plugin directly in the [`emigrate.config.js` file](../../../reference/configuration/).
### Configuration file
@ -76,7 +76,7 @@ The environment variables are used when the plugin is used using the `--plugin`
npx emigrate list --plugin mysql
```
Or when specifying the plugin in the [`emigrate.config.js` file](/reference/configuration) as a string:
Or when specifying the plugin in the [`emigrate.config.js` file](../../../reference/configuration) as a string:
```js title="emigrate.config.js" {2}
export default {

6
docs/src/content/docs/plugins/reporters/index.mdx
View file

@ -14,11 +14,11 @@ You can specify a reporter via the `--reporter` (or `-r` for short) option:
npx emigrate list --reporter pino
```
Or set it up in your configuration file, see [Reporter configuration](/reference/configuration/#reporter) for more information.
Or set it up in your configuration file, see [Reporter configuration](../../reference/configuration/#reporter) for more information.
## Available Reporters
<CardGrid>
<LinkCard title="Default Reporter" href="/reporters/default/" />
<LinkCard title="Pino Reporter" href="/reporters/pino/" />
<LinkCard title="Default Reporter" href="default/" />
<LinkCard title="Pino Reporter" href="pino/" />
</CardGrid>

4
docs/src/content/docs/plugins/reporters/pino.mdx
View file

@ -40,7 +40,7 @@ The `@emigrate/reporter-` prefix is optional when using this reporter.
emigrate <command> --reporter pino
```
See for instance the [Reporter Option](/commands/up/#-r---reporter-name) for the `up` command for more information.
See for instance the [Reporter Option](../../../commands/up/#-r---reporter-name) for the `up` command for more information.
### Via configuration file
@ -50,7 +50,7 @@ export default {
};
```
See [Reporter Configuration](/docs/configuration/#reporter) for more information.
See [Reporter Configuration](../../../reference/configuration/#reporter) for more information.
## Example output

2
docs/src/content/docs/plugins/storage/file-system.mdx
View file

@ -32,7 +32,7 @@ This is suitable for simple setups, but for more advanced setups for instance wh
## Configuration
The File System Storage can be configured easily in your [`emigrate.config.js` file](/reference/configuration):
The File System Storage can be configured easily in your [`emigrate.config.js` file](../../reference/configuration/):
```js {1,4-6}
import storageFs from '@emigrate/storage-fs';

8
docs/src/content/docs/plugins/storage/index.mdx
View file

@ -15,13 +15,13 @@ You can specify a storage plugin via the `--storage` (or `-s` for short) option:
npx emigrate list --storage mysql
```
Or set it up in your configuration file, see [Storage configuration](/reference/configuration/#storage) for more information.
Or set it up in your configuration file, see [Storage configuration](../../reference/configuration/#storage) for more information.
## Available storage plugins
<CardGrid>
<LinkCard title="File System" href="/plugins/storage/file-system/" description="The most basic storage plugin - for simple setups" />
<LinkCard title="MySQL" href="/plugins/storage/mysql/" description="A storage plugin that uses a MySQL database for storing the migration history state" />
<LinkCard title="File System" href="file-system/" description="The most basic storage plugin - for simple setups" />
<LinkCard title="MySQL" href="mysql/" description="A storage plugin that uses a MySQL database for storing the migration history state" />
</CardGrid>
:::note
@ -29,5 +29,5 @@ More storage plugins are coming soon!
:::
:::tip[Is your database missing?]
Writing a storage plugin is easy! Check out the [Storage Plugin API](/reference/storage-plugin-api/) for more information.
Writing a storage plugin is easy! Check out the [Storage Plugin API](../../reference/storage-plugin-api/) for more information.
:::

6
docs/src/content/docs/plugins/storage/mysql.mdx
View file

@ -4,7 +4,7 @@ title: MySQL Storage
import { Tabs, TabItem } from '@astrojs/starlight/components';
The MySQL storage plugin uses a MySQL database to store the migration history (*duh*). In the same package you can find the [MySQL Loader](/plugins/loaders/mysql/) and the [MySQL Generator](/plugins/generators/mysql/).
The MySQL storage plugin uses a MySQL database to store the migration history (*duh*). In the same package you can find the [MySQL Loader](../../loaders/mysql/) and the [MySQL Generator](../../generators/mysql/).
## Installation
@ -28,7 +28,7 @@ The MySQL storage plugin uses a MySQL database to store the migration history (*
## Configuration
The MySQL storage can be configured either using environment variables or by configuring the plugin directly in the [`emigrate.config.js` file](/reference/configuration).
The MySQL storage can be configured either using environment variables or by configuring the plugin directly in the [`emigrate.config.js` file](../../../reference/configuration/).
### Configuration file
@ -83,7 +83,7 @@ The environment variables are used when the storage plugin is used using the `--
npx emigrate list --storage mysql
```
Or when specifying the storage in the [`emigrate.config.js` file](/reference/configuration) as a string:
Or when specifying the storage in the [`emigrate.config.js` file](../../../reference/configuration) as a string:
```js title="emigrate.config.js" {2}
export default {

12
docs/src/content/docs/reference/configuration.mdx
View file

@ -47,7 +47,7 @@ Set the directory where your migrations are located, relative to the project roo
**type:** `string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)`
**default:** `"default"` - the default reporter
Set the reporter to use for the different commands. Specifying a [reporter](/plugins/reporters/) is most useful in a CI or production environment where you either ship logs or want to have a machine-readable format.
Set the reporter to use for the different commands. Specifying a [reporter](../plugins/reporters/) is most useful in a CI or production environment where you either ship logs or want to have a machine-readable format.
```js title="emigrate.config.js" {2}
export default {
@ -77,7 +77,7 @@ The default reporter automatically detects if the current environment is an inte
**type:** `string | EmigrateStorage | Promise<EmigrateStorage> | (() => Promise<EmigrateStorage>)`
Set the [storage plugin](/plugins/storage/) to use for storing and reading the migration history. This option is required by all Emigrate commands except `new` which doesn't use it.
Set the [storage plugin](../plugins/storage/) to use for storing and reading the migration history. This option is required by all Emigrate commands except `new` which doesn't use it.
```js title="emigrate.config.js" {2}
export default {
@ -86,7 +86,7 @@ export default {
```
:::note
Each storage plugin can have its own configuration options, see the corresponding [Storage Plugin](/plugins/storage/) section for more information.
Each storage plugin can have its own configuration options, see the corresponding [Storage Plugin](../plugins/storage/) section for more information.
:::
### `plugins`
@ -97,8 +97,8 @@ Set the plugins to use for the different commands. There are different types of
In short:
* [Loader Plugins](/plugins/loaders/) - are used for transforming non-JavaScript files into JavaScript files that can be executed by Node.js. These are only used by the `up` command.
* [Generator Plugins](/plugins/generators/) - are used for generating new migration files. These are only used by the `new` command.
* [Loader Plugins](../plugins/loaders/) - are used for transforming non-JavaScript files into JavaScript files that can be executed by Node.js. These are only used by the `up` command.
* [Generator Plugins](../plugins/generators/) - are used for generating new migration files. These are only used by the `new` command.
```js title="emigrate.config.js" {2}
export default {
@ -107,7 +107,7 @@ export default {
```
:::tip[Did you know?]
The same package can expose multiple plugins, so you can specify the plugin only once and it can be used as both a loader and a generator (and storage, in the case of [MySQL](/plugins/storage/mysql) for instance).
The same package can expose multiple plugins, so you can specify the plugin only once and it can be used as both a loader and a generator (and storage, in the case of [MySQL](../plugins/storage/mysql) for instance).
:::
### `template`