one-ox | links

Table of content

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

Keep Learning

PREVRANDOMNEXT