# one-ox | links

## http, https, mailto links

Web links (starting by `http` or `https`) and links to message composition (starting by `mailto`) are exported as we expect.

For instance the following link

    http://tonyaldon.com

is exported as follow

    <a href="http://tonyaldon.com">http://tonyaldon.com</a>

and rendered like this: http://tonyaldon.com.

This following link with a description

    [[https://tonyaldon.com][Tony Aldon (https)]]

is exported as follow

    <a href="https://tonyaldon.com">Tony Aldon (https)</a>

and rendered like this: Tony Aldon (https).

This `mailto` link

    [[mailto:tony@tonyaldon.com][send me an email]]

is exported as follow

    <a href="mailto:tony@tonyaldon.com">send me an email</a>

and rendered like this: send me an email.

## Custom ID links

In `one.el`, `CUSTOM_ID` org property is used to defined the path of pages or the path to specific heading in pages.

Considering the following org document

    * Home Page
    :PROPERTIES:
    :ONE: one-default-home
    :CUSTOM_ID: /
    :END:

    - [[#/blog/page-1/]]
    - [[#/blog/page-1/#headline-1]]

    * Page 1
    :PROPERTIES:
    :ONE: one-default
    :CUSTOM_ID: /blog/page-1/
    :END:
    ** headline 1 in Page 1
    :PROPERTIES:
    :CUSTOM_ID: /blog/page-1/#headline-1
    :END:

the link `[[#/blog/page-1/]]` in "Home Page" targets "Page 1" page and the link `[[#/blog/page-1/#headline-1]]` in "Home Page" targets the heading "headline 1 in page Page 1" in the "Page 1" page.

Those paths define valid web urls starting at the root of the website if we respect the following rules for `CUSTOM_ID` values:

1. we use only url-encoded characters,

2. we start them with a `/` and end them with `/` excepted for the home page which is a single `/`,

3. we use `#` character to start the last part of the path when we are targeting a heading tag with its `id` being the last part after the `#` character.

The benefits of these "rules/conventions" are:

1. when we export `custom-id` links using `one-ox` org backend we can leave them as they are and

2. the navigation between pages inside emacs using `custom-id` links works out-of-the-box.

### Example of a link to a page

The following link

    [[#/docs/one-ox-plain-list/][one-ox | plain-list]]

is exported to this anchor tag that links to the page `/docs/one-ox-plain-list/`:

    <a href="/docs/one-ox-plain-list/">one-ox | plain-list</a>

and is rendered like this one-ox | plain-list.

### Example of a link to a heading in a page

The following link

    [[#/docs/one-ox-plain-list/#unordered-lists][unordered lists heading in the page about plain-list]]

is exported to this anchor tag that links to the heading with the `id` set to `unordered-lists` on the page `/docs/one-ox-plain-list/`:

    <a href="/docs/one-ox-plain-list/#unordered-lists">unordered lists heading in the page about plain-list</a>

and is rendered like this unordered lists heading in the page about plain-list.

## Fuzzy links

I don't use `fuzzy` links. So, if there is a `fuzzy` link in the document, that means I wrote the link wrong.

Broken links are bad user experience. I don't like them.

So I decided that `one-ox` raises an error (hard-coded) when we try to export a fuzzy link to HTML.

For instance, the following `fuzzy` link:

    [[fuzzy search]]

raise an error like the following:

    (one-link-broken "fuzzy search" "fuzzy links not supported" "goto-char: 5523")

## File links

### Links to local files in assets and public directories

Links to local files in `./assets/` and `./public/` directories like

    [[./assets/foo/bar.txt][Bar file]]
    [[./public/foo/baz.txt][Baz file]]

are exported with the prefixes `./assets` and `./public` of the path removed like this:

    <a href="/foo/bar.txt">Bar file</a>
    <a href="/foo/baz.txt">Baz file</a>

### Local file links that raise one-link-broken error

Any file link that doesn't point to a file in `./assets/` or `./public/` subdirectories raises an `one-link-broken` error when we try to export it with `one-ox` org backend

For instance if we try to export using `one-ox` org backend the following link to the file `foo.txt` in the directory `/tmp/`

    [[/tmp/foo.txt]]

which is not in `./public/` subdirectory nor in `./assets/` subdirectory we will get an error like the following:

    (one-link-broken "/tmp/" "goto-char: 26308")

### Links to images

Links to local files in `./assets/` and `./public/` directories whom path matches `one-ox-link-image-extensions` regexp are exported with an `img` tag.

For instance the following link to an image in `./assets/img/` directory

    [[./assets/img/keep-learning.png][Keep Learning]]

is exported as follow

    <img href="/img/keep-learning.png" alt="Keep Learning"></a>

and rendered like this