The open-source protocol (The Org Manual)

Previous: The `capture` protocol, Up: Protocols [Contents][Index]

#### 16.14.3 The `open-source` protocol

The `open-source` handler is designed to help with editing local sources when reading a document. To that effect, you can use a bookmark with the following location:

    javascript:location.href='org-protocol://open-source?&url='+
          encodeURIComponent(location.href)

The variable `org-protocol-project-alist` maps URLs to local file names, by stripping URL parameters from the end and replacing the `:base-url` with `:working-directory` and `:online-suffix` with `:working-suffix`. For example, assuming you own a local copy of ‘`https://orgmode.org/worg/`’ contents at ‘`/home/user/worg`’, you can set `org-protocol-project-alist` to the following

    (setq org-protocol-project-alist
          '(("Worg"
             :base-url "https://orgmode.org/worg/"
             :working-directory "/home/user/worg/"
             :online-suffix ".html"
             :working-suffix ".org")))

If you are now browsing ‘`https://orgmode.org/worg/org-contrib/org-protocol.html`’ and find a typo or have an idea about how to enhance the documentation, simply click the bookmark and start editing.

However, such mapping may not always yield the desired results. Suppose you maintain an online store located at ‘`http://example.com/`’. The local sources reside in ‘`/home/user/example/`’. It is common practice to serve all products in such a store through one file and rewrite URLs that do not match an existing file on the server. That way, a request to ‘`http://example.com/print/posters.html`’ might be rewritten on the server to something like ‘`http://example.com/shop/products.php/posters.html.php`’. The `open-source` handler probably cannot find a file named ‘`/home/user/example/print/posters.html.php`’ and fails.

Such an entry in `org-protocol-project-alist` may hold an additional property `:rewrites`. This property is a list of cons cells, each of which maps a regular expression to a path relative to the `:working-directory`.

Now map the URL to the path ‘`/home/user/example/products.php`’ by adding `:rewrites` rules like this:

    (setq org-protocol-project-alist
          '(("example.com"
             :base-url "http://example.com/"
             :working-directory "/home/user/example/"
             :online-suffix ".php"
             :working-suffix ".php"
             :rewrites (("example.com/print/" . "products.php")
                        ("example.com/$" . "index.php")))))

Since ‘`example.com/$`’ is used as a regular expression, it maps ‘`http://example.com/`’, ‘`https://example.com`’, ‘`http://www.example.com/`’ and similar to ‘`/home/user/example/index.php`’.

The `:rewrites` rules are searched as a last resort if and only if no existing file name is matched.

Two functions can help you filling `org-protocol-project-alist` with valid contents: `org-protocol-create` and `org-protocol-create-for-org`. The latter is of use if you’re editing an Org file that is part of a publishing project.

Previous: The `capture` protocol, Up: Protocols [Contents][Index]