docums-redirects 1.0.0
A Docums plugin for dynamic page redirects to prevent broken links.
License: MIT
Requires Python: >=2.7
Keywords: docums redirect

# Docums Redirects

Plugin for [`docums`](https://khanhduy1407.github.io/docums) to create page redirects (e.g. for moved/renamed pages).

## Installing

> **Note:** This package requires Docums version 1.0.0 or higher.

Install with pip:

```bash
pip install docums-redirects
```

## Using

To use this plugin, specify your desired redirects in the plugin's `redirect_maps` setting in your `docums.yml`:

```yaml
plugins:
    - redirects:
        redirect_maps:
            'old.md': 'new.md'
            'old/file.md': 'new/file.md'
            'some_file.md': 'http://external.url.com/foobar'
```

_Note: don't forget that specifying the `plugins` setting will override the defaults if you didn't already have it set! See [this page](https://khanhduy1407.github.io/docums/user-guide/configuration/#plugins) for more information._

The redirects map should take the form of a key/value pair:

- The key of each redirect is the original _markdown doc_ (relative to the `docs_dir` path).
  - This plugin will handle the filename resolution during the `docums build` process.
    This should be set to what the original markdown doc's filename was (or what it _would be_ if it existed), not the final HTML file rendered by Docums
- The value is the _redirect target_. This can take the following forms:
  - Path of the _markdown doc_ you wish to be redirected to (relative to `docs_dir`)
    - This plugin will handle the filename resolution during the `docums build` process.
      This should be set to what the markdown doc's filename is, not the final HTML file rendered by Docums
  - External URL (e.g. `http://example.com`)

During the `docums build` process, this plugin will create `.html` files in `site_dir` for each of the "old" file that redirects to the "new" path.
It will produce a warning if any problems are encountered or of the redirect target doesn't actually exist (useful if you have `strict: true` set).

### `use_directory_urls`

If you have `use_directory_urls: true` set (which is the default), this plugin will modify the redirect targets to the _directory_ URL, not the _actual_ `index.html` filename.
However, it will create the `index.html` file for each target in the correct place so URL resolution works.

For example, a redirect map of `'old/dir/README.md': 'new/dir/README.md'` will result in an HTML file created at `$site_dir/old/dir/index.html` which redirects to `/new/dir/`.

Additionally, a redirect map of `'old/dir/doc_name.md': 'new/dir/doc_name.md'` will result in `$site_dir/old/dir/doc_name/index.html` redirecting to `/new/dir/doc_name/`.

This mimics the behavior of how Docums builds the site dir without this plugin.

## Contributing

- Pull Requests are welcome.
- File bugs and suggestions in the [GitHub Issues](https://github.com/khanhduy1407/docums-redirects/issues).

## Releasing

```bash
make release
```

It will prompt you for your PyPI user and password.

See:

- <https://packaging.python.org/tutorials/packaging-projects/>
- <https://packaging.python.org/guides/migrating-to-pypi-org/>