awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-01 12:17:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: awesome-emacs:v0.1.2
Branches Tags
awesome-emacs:main awesome-emacs:add-test awesome-emacs:doc-build awesome-emacs:gh-pages awesome-emacs:fix/2039 awesome-emacs:nobiot awesome-emacs:feat/unify-capture-templates awesome-emacs:filenotify awesome-emacs:fix/1763 awesome-emacs:feat/parent-dir awesome-emacs:migration/err awesome-emacs:v2-next awesome-emacs:flow
awesome-emacs:v2.3.1 awesome-emacs:v2.3.0 awesome-emacs:v2.2.2 awesome-emacs:v2.2.1 awesome-emacs:v2.2.0 awesome-emacs:v2.1.0 awesome-emacs:v2.0.0 awesome-emacs:2.0.0a1 awesome-emacs:v1.2.4 awesome-emacs:v1.2.3 awesome-emacs:v1.2.2 awesome-emacs:v1.2.1 awesome-emacs:v1.2.0 awesome-emacs:v1.1.1 awesome-emacs:v1.1.0 awesome-emacs:v1.0.0 awesome-emacs:v1.0.0-rc1 awesome-emacs:v0.1.2 awesome-emacs:v0.1.1 awesome-emacs:v0.1.0
...
compare: awesome-emacs:fix/1763
Branches Tags
awesome-emacs:add-test awesome-emacs:main awesome-emacs:doc-build awesome-emacs:gh-pages awesome-emacs:fix/2039 awesome-emacs:nobiot awesome-emacs:feat/unify-capture-templates awesome-emacs:filenotify awesome-emacs:fix/1763 awesome-emacs:feat/parent-dir awesome-emacs:migration/err awesome-emacs:v2-next awesome-emacs:flow
awesome-emacs:v2.3.1 awesome-emacs:v2.3.0 awesome-emacs:v2.2.2 awesome-emacs:v2.2.1 awesome-emacs:v2.2.0 awesome-emacs:v2.1.0 awesome-emacs:v2.0.0 awesome-emacs:2.0.0a1 awesome-emacs:v1.2.4 awesome-emacs:v1.2.3 awesome-emacs:v1.2.2 awesome-emacs:v1.2.1 awesome-emacs:v1.2.0 awesome-emacs:v1.1.1 awesome-emacs:v1.1.0 awesome-emacs:v1.0.0 awesome-emacs:v1.0.0-rc1 awesome-emacs:v0.1.2 awesome-emacs:v0.1.1 awesome-emacs:v0.1.0

695 Commits
v0.1.2 ... fix/1763

Author SHA1 Message Date
Jethro Kuan
82733e133a (fix)buffer: skip backlinks where file no longer exists 
This is a fix to #1763, and an alternative to #1765. The rationale for
not running a db-sync on buffer redisplay is that this is run on
`post-command-hook` and needs to be fast.
 2021-08-21 16:59:34 +08:00
Jethro Kuan
858f531d96 (feat)buffer: optimize reflinks fetch (#1795) 
Use SQL join instead of iterating over each ref and running another sql query.
 2021-08-21 16:18:41 +08:00
Jethro Kuan
f819720c51 v2.1.0 (#1792) 2021-08-21 02:57:40 +08:00
Wetlize
887c49c89c (docs)readme: update installation section (#1787) 2021-08-19 22:05:18 +08:00
Wetlize
d4cbb1d499 (feat): don't move the point when revisiting already visited nodes (#1788) 
This is now the default behavior for `org-roam-find-noselect` and
`org-roam-node-visit`, unless FORCE parameter set to non-nil.

Co-authored-by: Duncan Burke <duncankburke@gmail.com>
 2021-08-19 15:16:02 +03:00
Jethro Kuan
f29a770af3 (feat)org-roam-version: output commit hash when available (#1786) 
Output the commit hash when it's available (e.g. when using straight to
install packages). This comes in handy during debugging during error
reporting.
 2021-08-18 16:16:32 +08:00
Bram Schoenmakers
4a7ecfbed8 (fix): remove duplicate edges from graphs (#1768) 
When a node links to the another node twice, two edges appear in the
graph. To keep the graph clean, remove all duplicate edges.
 2021-08-18 15:50:57 +08:00
Jethro Kuan
df65654b2f (fix)completions: allow empty field-width (#1785) 
This allows the empty field-width to be used, but using an empty
field-width will result in misalignment. This is useful for people who
use completion frameworks like Ido.
 2021-08-18 14:03:16 +08:00
Wetlize
b627298171 (fix){preview,grep}-visit: always navigate to the source of the preview 
Previously when the preview and buffer would be opened, it would just
display the buffer at the last visited position without performing any
repositiong.

To enforce the correct behavior, the point should be always moved after
the buffer is visited, and not before.
 2021-08-18 00:39:42 +03:00
Jethro Kuan
b8a66deae9 (docs): link to org-roam-ui (#1782) 
Closes #1780
 2021-08-18 00:29:53 +08:00
Jethro Kuan
aafc8606bb (feat): add generalized template prefixes (#1723) 
Adds org-roam-node-template-prefixes to split and prefix node properties
as a query language during completions, and allow 0-width template portions.
 2021-08-17 23:40:56 +08:00
Wetlize
95afbc676a (refactor)org-roam-node-visit: always return the visited buffer 2021-08-16 23:20:11 +03:00
Wetlize
59faa3fdaa (fix): refactor error handling using ignore-errors 
(condition-case nil
    (test)
  (t nil))

Is a construct that's only available starting from Emacs 27. Since
Org-roam supports Emacs 26, gotta use what's given.

Note: ignore-errors isn't exactly the same as the construct above from
Emacs 27. Compare to ignore-errors to would trap all possible signals,
while ignore-errors will only trap "error" signals. This, however,
shouldn't affect us in case of this refactoring.

Fixes #1777.
 2021-08-16 22:25:12 +03:00
Samuel Loury
c51ce08a40 (fix)org-roam-link-replace-at-point: preseve match-data (#1766) 
It lies in between org-in-regexp and replace-match. In some situations, like
when the link looks like roam:a s'b, it changes the match-data.
 2021-08-16 21:48:29 +08:00
Wetlize
8d4de78fac (fix)org-id: gracefully handle absence of org-id-locations-file (#1769) 
This should be more useful than telling the user to run something
like (org-id-update-id-locations (directory-files-recursively ..))

org-id normally stores the org-id-locations-file in
user-emacs-directory, which should always exist if Emacs is installed.
If the path to the location exists, org-id will be able to create the
file on its own, however, configurations often change the location of
this file to a different one, in which case its path might not be
constructed of existing directories (on the file system) and org-id
won't be able to laydown this path for the user.

This causes org-id to throw unhelpful errors (like in #1734, #1700,
\#1688) that don't allow Org-roam to complete capture process or
properly finish migration, and possibly add malfunctions at other
layers.

Ideally this problem should be handled by org-id itself, but for now
this will be only patched in Org-roam.

Fixes #1700 and fixes #1638.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
Co-authored-by: David Wilson <david@daviwil.com>
 2021-08-16 21:38:47 +08:00
Wetlize
8a21131d9f (refactor)org-roam-link: use org-roam-node-visit to follow the links 
No need to get through org-id-goto, which would query to
org-id-locations instead of our own database.
 2021-08-14 00:01:25 +03:00
Wetlize
3c59c7d74e (feat): automatically reveal context when visiting nodes and files 
So if the user have folded content it will will automatically unfold the
surrounded context and reveal the thing at point. This should be very
useful for people who alter initial visibility of headings with
:VISIBILITY: property and of the whole file with something like
"#+startup: fold".
 2021-08-13 23:18:14 +03:00
Wetlize
5dce6261a2 (feat): replace org-roam-{setup,teardown} with org-roam-db-autosync-mode (#1758) 
Comply with the principle of least astonishment, where in Emacs having a
global minor mode for this purpose would be the most expected thing to
have.
 2021-08-10 14:02:17 +08:00
Brian Lester
39cd819cfa (fix)completions: fix candidate display (#1759) 
Recent changes to how candidates are formatted (using a display property
to allow for searching in the full candidate while only showing enough
to fit in the frame), #1754, causes problems when the field value is already
preformatted (a user function, like the one provided in doom emacs,
already applies some faces with `propertize`). Generally the display
string get messed up and formatting gets applied to the whole display.
This PR updates the call that add the display property to the candidate
to remove all the styling from the candidate before the styled (and
truncated) display string is added as a property. This allows the
display string to look correct according to the properties a user has
already assigned.

This PR also fixes another bug from this change, where if a
`field-value` is and empty string `""` it would not get padded out to
the `field-width` causing misalignments between candidates.
 2021-08-10 14:01:58 +08:00
Jethro Kuan
eb1d420c29 (feat)db: include self in outline (#1756) 
Include the current headline in outline extraction for links, so the
org-roam-buffer contains this information as well.
 2021-08-09 17:02:22 +08:00
Jethro Kuan
1f853ad8e6 (fix)completions: use full string (#1754) 
When strings in org-roam-node-display-template are truncated, they are
no longer searchable using completions, resulting in suprising
behaviour. This change allows truncated strings to still be searched
according to their original value. Closes #1728.
 2021-08-09 15:38:23 +08:00
Jethro Kuan
3c396f9e91 (fix)replace-link-at-point: preserve description (#1753) 
Preserve descriptions (if any) when replacing `roam:` links. Fixes #1737.
 2021-08-09 15:28:24 +08:00
Jürgen Hötzel
f227c03672 (fix)org-roam-db--file-hash: Always compute hash of encrypted file (#1725) 
When inserting the GPG decrypted org buffer to to DB, make sure that
the hash of the encrypted file is stored.

This prevents reparsing of GPG files over and over again when
synchronizing the database with the filesystem.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-08-09 15:13:45 +08:00
Jeremy Friesen
39b2388768 (feat): add :info key to org-roam-node-{capture/insert} (#1741) 
In adding this parameter, the external facing methods expose another
point of parameterization for the inner org-roam-capture- method.

This is most useful for the org-roam-node-insert method which has a
complicated inner logic; By adding the :info &key parameter, we
reduce the likelyhood of needing to duplicate that inner logic.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-08-09 15:09:10 +08:00
Benjamin Hipple
b24d874f26 (docs) fix typo in org-roam.org (#1747) 2021-08-09 15:01:57 +08:00
Jethro Kuan
dbb4c592fa (docs): Remove internal ID linking (#1751) 
Prefer headline links in docs, because internal id linking can cause
issues in documentation building. Closes #1749.
 2021-08-09 14:47:46 +08:00
Jürgen Hötzel
65b463d3c6 (minor)org-roam-format: Fix code formatting (#1726) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-08-08 14:03:10 +08:00
Wetlize
2d8dc8e31b (feat): globally restructure and refactor the codebase (#1724) 
Detangle the codebase and change how dependencies are resolved to
allow the package to better modularize and load itself without
introducing circular dependencies, especially when autoloads involved.
 2021-08-08 13:53:35 +08:00
Bram Schoenmakers
56e66f92d2 Force sync: close the database before removal (#1738) 
A force resync of the database does not work in Windows (Cygwin):

apply: Removing old name: Device or resource busy, /home/brschoen/.emacs.d/org-roam.db

Therefore, close the connection first and then try to remove the database file.
 2021-08-04 22:07:55 +08:00
Jethro Kuan
1d03f87cd1 (docs)capture: document default-val syntax and available expansions (#1721) 
Closes #1399.
 2021-08-01 14:26:31 +08:00
Jethro Kuan
48d1c152f5 (feat)db: add org-roam-db-update-on-save (#1720) 
Adds new variable org-roam-db-update-on-save, which when set to nil,
will disable db updates on file save. Closes #1717.
 2021-08-01 14:00:16 +08:00
Jethro Kuan
e8b720faad (minor)org-roam-get-keyword: make-obsolete (#1716) 
Prefer Org's org-collect-keywords over org-roam-get-keyword. This
function is not used anywhere, but perhaps some people's configurations
depend on it, so it will be left as is for now.
 2021-07-31 14:36:43 +08:00
Alan Zimmerman
cf918c3d18 (fix)capture: check if file exists on disk before template insertion (#1713) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-07-31 03:09:13 +08:00
Michael Eliachevitch
5fc57b2e06 (minor): correct type for INFO argument in org-roam-capture docstring (#1711) 2021-07-30 17:16:16 +08:00
Jethro Kuan
829ee68860 (feat): add org-roam-extract-subtree (#1710) 
Adds org-roam-extract-subtree, which converts the subtree at point
into a top-level file node. This is useful for when a node you are
expanding on gets too big, and deserves its own file.

Closes #1104, #1658
 2021-07-30 14:49:32 +08:00
Jethro Kuan
127d6efa48 (feat)org-roam-format: add default-value (#1709) 
Allow specification of default values in org-roam-format of the form ${key=default_val}.
 2021-07-29 23:27:55 +08:00
Jethro Kuan
d3b7c9b921 (fix)capture: check for buffer existence before template insertion (#1707) 
Redefine a new file to Org-roam's capture system as one that does not
have a buffer visiting it yet. This means that if a buffer is already
visiting the file, then the HEAD template will not be inserted. This is
important because Org-roam capture does not enforce the save of files,
and this can lead to scenarios where the template is inserted multiple
times to a buffer for a file that has not yet been written to disk.
 2021-07-29 22:39:24 +08:00
Brian Lester
a84da59b41 (fix)tags: splitting and joining of multiple filetags (#1705) 
Current, when fetching file level org tags (from the #+filetags property), multiple tags are split based on the default `split-string` separator. This is incorrect because the org documentation says that multiple file-level tags should be separated by `:` (like headline level tags). This results in a improper splitting (aka no split) of the tag string into multiple tags. This leads to the inability to delete tags that are there.

Similarly, when writing multiple filetags, the tags are joined by " " instead instead of ":" as mentioned in the org docs. This leads to improperly added tags where newly added tags would not be recognized by org.

This PR fixes both problems, parsing is done by string splitting on ":" (with the `OMIT-NULLS` parameter set to true so you don't get a null values from the fact tags start and end with `:`). Joining multiple tags is now done with the `org-make-tag-string` function instead of manually joining on space. These changes result in the ability to add and remove file level tags such that the resulting value of the `#+filetags` property is a valid tag string.
 2021-07-29 18:52:07 +08:00
Jethro Kuan
3f2d42142c (fix)org-roam-id-at-point: ignore top-level excluded nodes (#1704) 
Previously if a top-level file node is excluded, it would still be
picked up by org-roam-id-at-point. This adds another org-roam-db-node-p
check before returning an ID, fixing the broken behaviour. Fixes #1635.
 2021-07-29 11:15:14 +08:00
Jethro Kuan
b3b6277b96 (docs): roam_key -> ROAM_REFS (#1703) 
Also fixes #1697
 2021-07-29 02:09:53 +08:00
Wetlize
20514b7c6d (fix)autoloads: Exclude org-roam-graphs from patched autoload cookie 
`org-roam-graph` doesn't need the patch from #1673, because it sort of
lives on its own island, isolated from the rest of the codebase and can
simply do `(require 'org-roam)` when its autoload is fired.

Otherwise the autoload for this command will never end-up resolved,
because nothing `require`s it in the codebase.
 2021-07-28 20:34:59 +03:00
Matt Chowning
1db4c34c8a (fix): remove invisible tag (#1641) 2021-07-28 21:41:45 +08:00
Jethro Kuan
0c24540639 (feat): allow special 'ignore key in capture template (#1701) 
Allow 'ignore as a valid value in place of function
 2021-07-28 20:17:59 +08:00
Jethro Kuan
1848ca2495 (fix): fix url in v2 warning (#1695) 
Fixes #1689
 2021-07-28 02:20:23 +08:00
Jeremy Friesen
e31ac73a4d (feat): add filter-fn and templates to interactive commands (#1693) 
The rationale for this change is to allow context-specific capture
consideration.  That is to say, in my experience, when I'm working on a
project, I often want to scope my note finding and creation to that
project.  By adding `filter-fn` and `templates` I can easily craft
context-aware functions for my note-taking.

I chose to switch these to `cl-defun` to expose `&key` parameters, which I
find more useful as the method signature grows.

Closes #1681

From the Github Issue:

> Adding a `filter-fn` parameter to `org-roam-capture` and a `templates`
> parameter to `org-roam-capture` , `org-roam-node-insert`,
> `org-roam-node-find` would improve their general utility, and reduce
> fiddling with the more inner functionality of `org-roam-capture-` and
> `org-roam-node-read`
 2021-07-28 02:16:00 +08:00
Jethro Kuan
33ed817826 (fix)db: skip nodes with no title (#1694) 
In scenarios where a headline node has no title, skip the node instead
of erroring out. Fixes #1692.
 2021-07-28 02:11:08 +08:00
Wetlize
de47f0a28d (fix)autoloads: Point autoloads to org-roam.el file (#1673) 
At the current state autoloads from non `org-roam.el` unable to start
loading of the package from their own file. See the following to learn
more about the problem:

  https://github.com/org-roam/org-roam/issues/1590#issuecomment-885817825

This is no more than a workaround to bandage a more deeper underlying
problem. Until the more fundamental problem won't be fixed, all autoload
cookies from non "org-roam.el" file will need to manually point to the
main entry point of the package -- "org-roam.el" file, to load it
without causing errors.

Fixes #1590, #1620, #1600 and other similar issues.
 2021-07-27 20:33:50 +08:00
Jethro Kuan
04a0fec5c1 (docs): Add intro video to README (#1685) 2021-07-27 13:28:22 +08:00
Thomas von Eyben
7723f6ca88 (fix): correct typo about v1 being incompatible with v1 (#1682) 2021-07-27 11:56:55 +08:00
Jethro Kuan
6dc8dda5e5 (fix)preview: fix link preview when headline contains link (#1676) 2021-07-26 13:48:50 +08:00
Wetlize
4455762c38 (fix)capture: Adjust the point for capture targets in missing places (#1675) 
The previous fix[0] for capture targets did the right thing. However, it
didn't account that `org-roam-capture--get-point` branches to 3
different paths, where each of them set the point to a different
location, and the fix only addressed the branch in which
`org-roam-capture--goto-location` would run.

This commit adjusts the point for all other branches, which fixes a
problem where you would try to run capture to existing node with
something like `org-roam-capture` and it wouldn't set the point to the
right location; same with ref capturing through the `org-roam-protocol`.

[0]: c9bed390b6
 2021-07-26 11:38:05 +08:00
Jethro Kuan
6ce07cdbf7 (fix) org-roam-get-keyword: fix for cjk characters (#1672) 2021-07-25 23:07:51 +08:00
Jethro Kuan
9acd982332 (docs): add org-id-link-to-org-use-id to FAQ (#1670) 
Address a common question about Org-roam creating IDs
 2021-07-25 10:31:20 +08:00
Jethro Kuan
028c95a011 (fix)migration: upgrade db to v2 before conversion (#1666) 
`org-roam-migrate-v1-to-v2` requires the v2 db to already be in place,
so run `org-roam-db-sync` once first.

Fixes #1664
 2021-07-24 16:54:46 +08:00
Wetlize
d1e3a5d9be (feat): formalize node dedicated buffers (#1622) 
This adds the whole new section in `org-roam-mode.el` for node dedicated
buffers, with a new global command `org-roam-buffer-display-dedicated`,
which supersedes `org-roam-buffer` command.

Along the way this also refactors the code for the persistent buffers to
clean it up, make it more clear in what it does, improve its robustness,
and to make it play nice with the dedicated buffers.
 2021-07-23 19:19:30 +08:00
Jethro Kuan
8e89bad945 (migration)docs: Warn requirement of at least Org 9.4 (#1663) 
Closes #1661
 2021-07-23 19:17:47 +08:00
Jethro Kuan
9c10a3c04c (feat)preview: improve org-roam link preview (#1655) 
1. If it the link is at a headline, it shows the headline's content
instead of just repeating the headline
2. If the link is a bullet item in the plain-list, show the full list instead
 2021-07-22 01:46:12 +08:00
Jethro Kuan
1aba91eacd (fix)tags: fix tags migration (#1653) 
- prevent botching of existing filetags
- insert new tag list using `org-make-tag-string` (colon-delimited) for resilience

Fixes #1642.
 2021-07-21 23:25:04 +08:00
Jethro Kuan
2fe233ffa0 (fix)dailies: prevent non-compliant dailies from breaking calendar (#1652) 
ht @mbafford for finding the cause
 2021-07-21 23:03:03 +08:00
Jethro Kuan
d9015cb931 (fix): fix org-roam-file-p crashing (#1651) 
org-roam-file-p throws `wrong-type-argument stringp nil` on buffers that
do not have a corresponding file. This fix changes org-roam-file-p to
return nil instead of crashing in this scenario.

Addresses #1645
 2021-07-21 20:57:59 +08:00
Jethro Kuan
7d5b7e6185 (fix): fix org-ref cite links (#1637) 2021-07-20 16:25:54 +08:00
Jethro Kuan
3ea433c09d (migration): mention org-roam-directory (#1636) 
Mention the requirement to set org-roam-directory before running the
migration wizard. Closes #1624.
 2021-07-20 15:17:28 +08:00
Jethro Kuan
e5c735c86a (docs): remove apt installation (#1634) 
Apt installation is only valid for Org-roam v1. To be re-added when
Debian updates their repos. Closes #1631.
 2021-07-20 15:10:01 +08:00
Stanley Chan
23605546d8 (docs): mention magit-section as dependency in install from source (#1618) 2021-07-19 17:30:52 +08:00
Gustavo
f50e30dd51 Include desc back in replace-match statement (#1615) 
Following @jcguu95's suggestion on #1602.
 2021-07-19 10:38:19 +08:00
Alexey Shmalko
a529b20a81 fix(#1575): fix display of non-ASCII in unlinked references section (#1616) 
Non-ASCII characters are displayed incorrectly because
`org-roam-unlinked-references-preview-line` uses
`insert-file-contents-literally` which ignores the encoding.

Use `insert-file-contents` which does the right thing.

fixes #1575
 2021-07-19 10:36:21 +08:00
Nguyễn Đức Hiếu
6cbd4ad3e8 org-roam-mode-sections -> org-roam-mode-section-functions (#1612) 2021-07-19 10:35:40 +08:00
Carwin Young
e997c017de (docs): adjusted configuration examples for backlinks buffer (#1610) 
- Fixed the original example's extra parenthesis, which broke the alist.
 - Added a second example for configuring the buffer as a side window.
 2021-07-19 01:31:34 +08:00
Jethro Kuan
63450e9eaf migration: proper fix for file-link replacement (#1609) 2021-07-18 23:23:04 +08:00
Jethro Kuan
da02453ab1 (fix): migration: ensure empty roam_alias is removed (#1608) 
* (fix): migration: ensure empty roam_alias is removed

Addresses #1596

* fix lint
 2021-07-18 23:08:59 +08:00
Wetlize
bbf1d97eb0 (refactor): move all the backward compatibility related code to org-roam-compat.el (#1595) 2021-07-18 22:50:45 +08:00
Donovan
7d9fcf5288 (docs) Replace mention of org-roam-db-build-cache with org-roam-db-sync (#1606) 2021-07-18 21:43:34 +08:00
Jethro Kuan
d0be7f3b2a (fix): allow migration for desc with backslash (#1604) 
Fixes #1602
 2021-07-18 19:51:05 +08:00
Sidharth Arya
363dca1765 (doc): add my braindump example (Sidharth Arya) (#1599) 2021-07-18 19:35:18 +08:00
Jethro Kuan
4c5a041556 (docs): add note on encryption (#1597) 2021-07-18 14:55:32 +08:00
Noboru Ota
5e42d854c1 (doc): Add section for C Compiler (#1593) 
* (doc): Add section for C Compiler

In the Post-Installation Tasks section, I suggest to add a sub-section for the C
compiler requirement for emacsql-sqlite. I have put an explanation for Windows
-- I have tried to make it as succinct as I can without losing some fine points
that I believe important for users to avoid confusion.

I have just removed MSYS2 and the PATH on my Windows machine and repeated the
process as I described it here to confirm that it works.

Since this new part is distinct from the existing paragraphs for SQLite, I also
suggest a sub-section heading for them -- I used "SQLite" as its title.

Please feel feel to change any part as you see fit.

It might be also useful if macOS users added their parts. I believe XCode is the
easiest way to install a C compiler (I believe it would be clang for recent
XCode versions) or perhaps brew. I don't use macOS so I will refrain from adding
this part..

I did not add .texi file to this commit -- last time, I believe you had to
revise the texi file that my machine generated anyway. Let me know if I should
follow up with a texi file.

* remove reference to emacsql-sqlite3

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-07-18 14:39:30 +08:00
Wetlize
681873759d Refactor some docstring and parameters in org-roam.el (#1594) 
This mostly goes over docstrings, updating them in places where it was
outdated and adding them to places where they didn't exist or were
existed as placeholders.
 2021-07-18 14:22:45 +08:00
Jethro Kuan
2168490d5a bump docs for Org-roam v2 (#1591) 2021-07-17 22:54:31 +08:00
Jethro Kuan
3a78422a09 (fix): update filter-fn docstring (#1589) 
Fix inconsistency for filter-fn in ref and node functions, and update
docstrings to be consistent.
 2021-07-17 21:09:38 +08:00
Jethro Kuan
aee3467b3e Org-roam V2 (#1401) 2021-07-17 19:29:30 +08:00
Kisaragi Hiu
756f6215b6 (feat): allow setting #+roam_alias and #+roam_tag on multiple lines (#1540) 
This brings them more in line with how other Org keywords, such as
\#+PROPERTY, are declared.

Previously

    #+roam_alias: abc def
    #+roam_alias: ghi

would result in only the last one ("ghi") being extracted. Now ("abc"
"def" "ghi") are all extracted (in that order).

* org-roam.el (org-roam--extract-tags-prop, org-roam--extract-titles-alias): Accept and return all values in a list, not just from one line.
(org-roam--extract-prop-as-list): New function. List prop extraction refactored from `org-roam--extract-tags-prop` and `org-roam--extract-titles-alias`

* tests/test-org-roam.el: Add tests for defining tags and aliases in multiple lines
 2021-06-09 20:21:08 +08:00
Kisaragi Hiu
53c9a16e90 (fix): files not excluded when org-roam-list-files-commands is nil (#1542) 2021-06-09 20:07:47 +08:00
Jethro Kuan
8ad1414030 (fix): tags: fix vanilla option (#1520) 
Set `org-file-tags` before pulling tags from buffer. Should fix the
'vanilla option in `org-roam-tag-sources`
 2021-05-13 15:04:49 +07:00
Leo Vivier
f754160402 (fix): Fix chronology issue between renaming notes and updating links (#1517) 2021-05-12 09:06:11 +02:00
Greg
02e35e3b01 (feat): add org-roam-graph-filetype (#1513) 
Co-authored-by: Greg Coladonato <gcoladonato3@gatech.edu>
 2021-05-06 19:23:46 +08:00
Troy Hinckley
d2e933cc3e Fix auto save buffer in org-roam-doctor (#1493) 2021-05-03 03:36:09 +08:00
Noboru Ota
15c1a46e41 (doc): Add file-truename to set org-roam-directory (README and documentation) (#1487) 
* (doc): Add file-truename to set org-roam-directory

Refer this debuging Slack exchange:
https://orgroam.slack.com/archives/CV160S8EL/p1619089118195300

Not using `file-truename` to set
`org-roam-directory` can lead to an issue that is
hard to identify.

It appears that cache database may updates with
files but `org-roam-buffer` fails to find the file
as symbolic links do not resolve. This is
confusing as the table query to the table seems to
return what appears to be correct entries, but the
backlink fails to insert context around the
link (as Org-roam fails to find the file).

There have been similiar issues -- by making sure
`file-truename` is added in the documentation and
README, it is hoped to eliminate such issues to
recur.

This is probably relevant for V2.

* undo changes to texi

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-04-28 13:43:42 +08:00
HyunggyuJang
9065f6a999 (fix) make roam headline link completion robust (#1473) 
Fixes  #1472
 2021-04-16 13:02:48 +08:00
Jethro Kuan
997ddcbf4b (docs): update org-roam dir-locals 
use absolute path instead of relative path to prevent errors
 2021-04-11 14:50:11 +08:00
USAMI Kenta
2d58651699 optimize filename normalize (#1460) 
* Normalize slug using ucs-normalize-NFC-string after remove Unicode spacing mark
* Add org-roam-slug--preserve-chars-from-normalization for Unicode Normalization
* Add org-roam-slug-trim-chars instead of org-roam-slug--preserve-chars-from-normalization
 2021-04-05 21:35:58 +08:00
Sean Farley
8ad57b1218 (fix): support %i in org-roam-protocol (#1445) 2021-03-08 12:57:38 +08:00
Jethro Kuan
0b964ca428 (fix): fix org-roam buffer insert out-of-order (#1448) 2021-03-06 18:01:48 +08:00
Sean Whitton
643b98eeb3 (fix): dailies: avoid assuming value of org-roam-dailies-directory (#1426) 2021-03-06 10:51:29 +08:00
Jürgen Hötzel
b0fd12647b (fix): dailies: prevent inclusion of non-org-roam files (#1409) 
Fixes #1398
 2021-01-28 21:41:42 +08:00
Boris Buliga
fde40dc1c4 (fix) parsing of missing props (#1406) 
Followup from #1404
 2021-01-26 14:45:19 +08:00
Boris Buliga
96b0a52273 (fix) inconsistency between props writing and reading (alias, tags) (#1404) 
Fixes #1403
 2021-01-26 11:09:19 +08:00
Marlin Strub
aa52b65a4a (feat): add org-roam-file-completion-tag-position (#1396) 2021-01-23 18:09:52 +08:00
Paul Gowder
2a1c73c0a3 (docs): clarify behavior of capture functions (#1393) 2021-01-20 21:55:17 +08:00
Jethro Kuan
16c7a7bd93 (doc): update mac protocol instructions (#1390) 
use native script editor, rather than Platypus.
 2021-01-18 23:02:53 +08:00
Jethro Kuan
1b3a0abd36 (feat): add org-roam-buffer-preview-function (#1388) 
Instead of storing preview content in the database, now provide a
function to fetch these on the fly. This paves the way for future
improvements (e.g. showing more lines)
 2021-01-17 02:52:39 +08:00
Jethro Kuan
06e5814898 (fix): org-roam-dailies: fix false warning on new file (#1387) 
Fixes #1358
 2021-01-16 21:06:50 +08:00
Alexey Shmalko
cc2572e48b (doc): add my braindump example (Alexey Shmalko) (#1384) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-01-16 20:44:15 +08:00
Thomas Sojka
05deb64d85 (doc) Update brew install script (#1386) 
The API for Homebrew Cask changed (https://brew.sh/)
 2021-01-16 16:58:13 +08:00
Samuel W. Flint
f10fbad386 (feat): allow org-roam-buffer-position to be a function (#1385) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2021-01-16 13:43:00 +08:00
Jethro Kuan
05a9bc44f2 (fix): fix org-roam-capture--get-point (#1376) 2021-01-11 19:38:02 +08:00
Jethro Kuan
3fb4e21adf (fix): fix org-roam-protocol--open-ref creating new files (#1375) 
We need to split the ref into its type/file before querying the db for a
match. Throw a warning when `org-roam--capture-new-file` tries to
recreate an existing file.
 2021-01-10 23:05:45 +08:00
Nathanael kinfe
62bba9755c (fix): keep id backlinks on filename change (#1367) 2021-01-10 16:01:15 +08:00
Jethro Kuan
78a371cdc4 (fix): fix headline completions erroring (#1374) 
updates org-roam-with-file to accept nil FILE arg, to operate on current
buffer. Fixes org-roam-link--get-headlines to kill buffer if not
obtaining markers.
 2021-01-09 17:49:36 +08:00
Tyler Smith
15d864a500 (feat): add useful warning message to org-roam-dailies-find-next-note (#1365) 
If the user creates a new daily via `org-roam-dailies-find-today`, they
will get a new buffer that hasn't yet been saved to disk. If they then try
to navigate to the previous daily via
`org-roam-dailies-find-previous-note`, they will get the error:

    `Wrong type argument: number-or-marker-p, nil`

This is because the value of the local variable `position` is set only if
the current buffer exists as a file in the dailies directory. It doesn't
until the user explicitly saves it.

That's not a big problem, but the solution is not obvious from the error
message. I added a check that will provide the user with a more informative
error message, so they know how to fix the issue:

    "Can't find current note file - have you saved it yet?"
 2021-01-01 12:48:20 +08:00
Samuel Loury
65c0f0dc8c (feat): use org-link-display-format in org-roam-insert (#1356) 
So that, like org-store-link, the computed description does not
contain the links that were captured.
 2020-12-25 13:43:41 +08:00
Jethro Kuan
48e195dd82 (refactor): refactor org-roam-capture (#1355) 2020-12-22 21:57:02 +08:00
Jethro Kuan
777f6d23ec (feat): Support file-property drawers (#1353) 
* (feat): Support file-property drawers

Add support for file-property drawers in property extraction. This means
the following is now supported:

:PROPERTIES:
:ROAM_ALIAS: alias
:ROAM_TAGS: tag1 tag2
:END:
 2020-12-19 23:59:40 +08:00
Jethro Kuan
8f1cf7b449 (fix): set-global-prop: prefer lowercase (#1352) 
Prefer lower-case version of Org properties. Fixed bug where
adding/deleting props will alter the original case of the Org property.

Addresses #1342
 2020-12-19 19:23:27 +08:00
Jethro Kuan
3ce6e299d4 (doc) Update README (#1351) 2020-12-19 17:53:25 +08:00
Noboru Ota
ecf515f650 (doc): Add footnote for tab completion (#1348) 
Follow on to #1345.

The discussion in the Slack thread further clarified what was exactly
confusing for a beginner reader of this Getting Started. When a user is using
the built-in completion (no ivy, no ido), then `org-roam-find-file` does not
immediately show any files -- instead, the user has to press TAB. This is not
explicitly mentioned.
 2020-12-19 16:42:43 +08:00
Jethro Kuan
43831c5819 (fix): allow link captures (#1347) 
Previously we had set `org-capture-link-is-already-stored` to `t` in
org-roam captures, because org-roam-protocol stores links. This
prevented regular captures from utilizing the %a element in the
templates.

Instead, only set `org-capture-link-is-already-stored` in the
org-roam-protocol capture command.

Fixes #1341.
 2020-12-16 21:12:21 +08:00
Noboru Ota
4d63f99fe8 (doc): Add async update to Getting Started (#1345) 2020-12-16 20:58:13 +08:00
Alois Janíček
57cfb3dbb7 (fix): index file: prevent malformed absolute path (#1346) 
When `org-roam-directory` doesn't end with trailing slash and
`org-roam-index-file` contains relative filename, absolute path
to org-roam index file returned by `org-roam--get-index-path` is
malformed and invalid.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-12-16 20:31:32 +08:00
Jethro Kuan
9c23218553 (docs): fix docstring for org-roam--get-title-path-completions (#1344) 2020-12-15 20:26:43 +08:00
Nathanael kinfe
7ad32e8395 (feat): make org-roam-buffer-update interactive (#1343) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-12-15 20:04:48 +08:00
Kisaragi Hiu
d87dd011aa (fix): preserve existing description in a roam: link on replace (#1327) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-12-15 19:47:51 +08:00
Nathanael kinfe
f2976fa3be (fix): close files intelligently after modifying (#1330) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-12-15 18:33:55 +08:00
Win Treese
8aa793b021 (docs): org-roam-doctor: fix docs for prefix arg (#1337) 2020-12-12 14:34:04 +08:00
asymmetric
be95b42d32 (docs): fix link to org-capture (#1329) 
Required capitalization.
 2020-12-01 12:42:33 +08:00
Jethro Kuan
cff1168ac1 (doc): fix link to manual (#1328) 2020-11-28 19:44:15 +08:00
Jethro Kuan
06d0db736a (internal): remove error-checking for olp (#1326) 
The `org-roam-capture-find-or-create-olp` function will throw the same
error, so we don't have to explicitly catch and throw.
 2020-11-24 21:09:28 +08:00
Jethro Kuan
fb0662efe7 (fix): uniqify title and tag extraction (#1325) 
Remove duplicates from title and tag extraction, arising from
multiple (or the same) sources.

Fixes #1324
 2020-11-24 20:00:49 +08:00
Jethro Kuan
9ca5461a2f (fix): fix mode toggle not re-enabling buffer-local hooks (#1321) 2020-11-23 19:59:30 +08:00
Jethro Kuan
33805c3ff5 (fix): don't set default-directory if no file is passed (#1318) 
This fixes calls like (org-roam--with-temp-buffer nil ...). Fixes #1310, #1316.
 2020-11-21 16:42:50 +08:00
Jethro Kuan
3a4ff76508 (fix): dailies: fix capture changing window configuration (#1314) 
`*-captures` commands now maintain window configuration, while the
`*-find` commands change to the file.
 2020-11-21 01:27:03 +08:00
Jethro Kuan
bf41352c1c (fix): fix title change not triggering rename if new title contains old (#1315) 
title

Fixes #1303
 2020-11-20 21:32:36 +08:00
Jethro Kuan
1b598a4618 (fix): dailies: misc fixes (#1309) 
Fixes #1293
 2020-11-19 23:00:33 +08:00
Jethro Kuan
ab34dd138d (fix): fix rename file corrupting database (#1308) 
The rename file advice is passed relative file names: e.g. "foo.org" ->
"bar.org". This was not accounted for, and paths in the Org-roam
database are supposed to be absolute paths. This caused the storing of
relative paths in the Org-roam database, which were then never purged.

Fixes #1304
 2020-11-19 22:26:59 +08:00
Jethro Kuan
b17cc3b1e3 (internal): org-roam-db--update-maybe -> org-roam-db--upgrade-maybe (#1307) 2020-11-19 21:55:07 +08:00
Jethro Kuan
f9b1e53894 (fix): do not display buffer if it is not processed in db (#1302) 
Finding an Org-roam file that does not exist yet triggers the find-file
hook, resulting in an Org-roam buffer update, attempting to show the
file. However, if the file does not yet exist, attempts to show the file
will not work, since the database does not contain the relevant
information yet.

This bug has always been present, but was only recently made visible by
the code cleanups in #1284.

Now, we ensure that the file has been processed by the database before
attempting to re-display the buffer.

Fixes #1297
 2020-11-18 20:24:21 +08:00
Tim Quelch
dbed2bcf5d (fix): set default-directory in org-roam-with-temp-buffer (#1300) 
This ensures that relative paths in keywords such as `#+setupfile:` and
`#+include:` work when building cache etc.
 2020-11-18 18:33:57 +08:00
Jürgen Hötzel
060a29c91d (fix): use correct type for org-roam-db-update-method (#1295) 
Fixes #1294.
 2020-11-18 18:17:00 +08:00
Jethro Kuan
8efec080e0 (ci): fix ci test flow (#1301) 2020-11-18 18:07:05 +08:00
Natnael Kahssay
61e01430e0 (perf): improve database update on 'immediate (#1285) 2020-11-16 21:27:23 +08:00
Natnael Kahssay
d70198bba9 (fix): fix cache updates on org-id creation in non-existing files (#1288) 
closes #1287
 2020-11-16 10:38:58 +08:00
Jethro Kuan
face683e00 (internal): remove org-roam--get-title-or-slug function (#1284) 
Every file has a title when saved into the database, so this function is
redundant in most cases (e.g. in org-roam-buffer, where backlinks are
fetched from the database).
 2020-11-15 19:44:36 +08:00
Jethro Kuan
baf0dd9d00 (doc): document tag completions (#1282) 2020-11-15 14:36:49 +08:00
Jethro Kuan
a9fd6c0fc7 (fix): fix idle-timer not created on org-roam-mode (#1281) 
Fixes #1280
 2020-11-15 14:21:03 +08:00
Jethro Kuan
6502874576 (doc): document completion-at-point (#1279) 2020-11-15 04:43:57 +08:00
Jethro Kuan
8401784cd2 (doc): document org-roam-tag-sources (#1274) 2020-11-14 21:12:08 +08:00
Jethro Kuan
6dc316c450 (doc): fix menu-comment styling (#1273) 2020-11-14 14:17:08 +08:00
Jethro Kuan
48ef3fee11 (doc): document org-roam-title-sources (#1271) 2020-11-13 22:55:52 +08:00
Alan Schmitt
16c520068b (doc): Fix typo (#1272) 
The `olp` option in the lab notes example was swapped.
 2020-11-13 14:22:58 +01:00
Jethro Kuan
b1608bf869 (feat): capture: create OLP if does not exist (#1270) 
Remove the requirement that the OLP already exists in the captured file.
Also, make OLP available beyond dailies functionality.
 2020-11-13 16:29:00 +08:00
Jethro Kuan
cc01cf346e (release): v1.2.3 (#1269) 2020-11-13 14:22:18 +08:00
Jethro Kuan
eaf99cba03 (doc): minor changes (#1268) 2020-11-13 13:17:28 +08:00
Tomasz Skupiński
65a2cb6efd (fix): readme: fix link to manual 2020-11-13 02:52:48 +08:00
Jethro Kuan
bc12d1cf04 (feat): add org-roam-db-update-method (#1264) 
* (feat): add `org-roam-db-update-method`

Add `org-roam-db-update-method`, which can be one of two choices:

1. `immediate`: the cache is updated upon file changes
2. `idle-timer`: Marks the org-roam database as dirty. If Emacs idles
for some seconds, the Org-roam cache is updated. This is the default,
and current behaviour.

The idle method makes for a smoother editing experience, but some
inconsistencies can be faced.

* org-roam-update-db-idle-seconds -> org-roam-db-update-idle-seconds
 2020-11-12 19:48:40 +08:00
Jethro Kuan
a86d82b20e (fix): fix backlink-to-current-p killing buffers (#1263) 
Change `org-roam--backlink-to-current-p` to only perform a DB query.
 2020-11-12 16:11:35 +08:00
Jethro Kuan
d4c875b53b (doc): doc stylistic changes (#1262) 
- style tables properly
- reduce pre font-size
 2020-11-12 15:40:27 +08:00
Leo Vivier
2159b6a846 (web): Remove mention to company-org-roam on index.html (#1261) 2020-11-12 08:27:22 +01:00
Jethro Kuan
1db4c22950 (doc): remove top-level TOC (#1260) 2020-11-12 15:13:59 +08:00
Jethro Kuan
9c0f030ffd (doc): add indexes (#1259) 
Add keystroke, command, function and variable indexes
 2020-11-12 14:56:48 +08:00
Leo Vivier
983d7a8798 (doc): Link org-journal to section on daily-notes (#1258) 2020-11-12 07:47:44 +01:00
Jethro Kuan
910b37268e (doc): make manual single-page (#1257) 
This should make things easier to browse/search for. Also simplify styling.
 2020-11-12 14:32:59 +08:00
lytex
d39556a78b (fix): unlinked-references: support filenames with spaces (#1256) 2020-11-12 12:05:14 +08:00
Kisaragi Hiu
167553b8ee (doc): various improvements (#1253) 
- options: explicitly enable smart quotes on export
- zettelkasten introduction: add sections for fleeting notes and
  permanent notes for easier access and reference
- anatomy: add a missing period
- encryption: clarify org-roam-encrypt-files is a user option
- roam protocol: remove extraneous heading
- roam protocol: small grammar fix
- doctor: explain what the doctor does by default
- org-roam-bibtex: explain part of what orb actually does
 2020-11-11 18:04:09 +08:00
Kisaragi Hiu
76affe177a (doc): reflect that we now allow multiple refs (#1251) 2020-11-11 15:42:45 +08:00
Jethro Kuan
e96685b1a9 (fix): respect original link type during replacement (#1252) 
During automatic link replacement, respect the original link type
i.e. absolute links remain absolute. Fixes #1228.
 2020-11-11 14:25:50 +08:00
Jethro Kuan
aef71f1623 (docs): use ox-texinfo+ (#1250) 
This generates texi documents with understanding of variables and
functions.
 2020-11-11 13:00:49 +08:00
Leo Vivier
d913447939 (fix): Fix command signature (#1247) 2020-11-10 18:04:59 +01:00
Leo Vivier
47e83f7d3f (fix): Deprecate old ord commands (#1246) 2020-11-10 17:57:26 +01:00
Jethro Kuan
023bcce867 (internal): remove unnecessary variables (#1244) 
For captures, enforce that `:file-name` needs to be specified, and
`:head` when not provided defaults to the empty string (i.e. no head)
 2020-11-10 23:58:16 +08:00
Leo Vivier
4f6eb285bf (feat): Overhaul org-roam-dailies (#978) 
Implement ideas from `org-journal` to `org-roam-dailies`.

Update the doc.
 2020-11-10 14:31:38 +01:00
Robert Irelan
8c81104816 (feat): unlinked-references: add error message if rg has no PCRE2 support (#1243) 2020-11-10 13:48:50 +08:00
Leo Vivier
7602b8c48d (feat): Allow ORP to capture the webpage's selection (#1239) 
* (feat): Temporarily store link when capturing with ORP

* org-roam-protocol.el (org-roam-protocol-open-ref): Replicate default
`org-protocol' behaviour temporarily for storing links
* org-roam-capture.el (org-roam-capture--capture): Prevent stored link from
being reset

When capturing a web-page with org-roam-protocol, a link is now temporarily
stored in `org-store-link-plist' via `org-link-store-props'.  This is to allow
the forwarding of properties to `org-capture', one of them being `:initial'
which contains the content of the selected text in the browser.

* (feat): Add toggle for storing link when capturing with ORP

* org-roam-protocol.el (org-roam-protocol-store-links): Add new toggle
(org-roam-protocol-open-ref): Conditionally store link for later used

Building up on b2ee5f2c68, the user can now
decide whether to store links when capturing with org-roam-protocol (default
nil).

* Update changelog
 2020-11-08 13:30:16 +01:00
Kisaragi Hiu
c6797cbd75 (feat): Allow one file to have multiple roam_key statements (#1215) 2020-11-07 15:33:31 +08:00
Jethro Kuan
440461a90b (feat): add org-roam-prefer-id-links to select linking method (#1238) 2020-11-07 15:06:12 +08:00
Jethro Kuan
4d423a916e (doc): add note on unlinked references and encrypted files (#1236) 2020-11-05 16:34:11 +08:00
Samuel Loury
b184cdaef0 (feat): use :preselect for ivy-read completions (#1234) 
This way, in case of the initial-input being an exact match, ivy will suggest this one first.
 2020-11-04 17:37:50 +08:00
Jethro Kuan
b2cc997976 (fix): fix relative link replacement (#1233) 2020-11-04 15:25:08 +08:00
Herbert Jones
bc5c41d212 (fix): widen before title extraction (#1232) 
Prevent renaming file and changing links incorrectly due to using (org-narrow-to-subtree) and saving.
 2020-11-04 13:34:40 +08:00
Matt Chowning
7c83a84db3 (fix): only update relative path of file links (#1226) 2020-11-04 00:07:31 +08:00
Kisaragi Hiu
56c47fbff8 (internal): make sure there are no byte-comp warnings... (#1220) 
...about undefined functions or unused lexical variables.

Undefined functions: for example, s.el and org-element should be
`require`'d when their functions are used.

Unused lexical variables: if Org isn't loaded yet, dynamic variables
defined in org.el would be treated as lexical and byte-comp would emit
this warning. This is especially important in the future as
native-comp / gccemacs will optimize away unused lexical variables,
and we cannot rely on Org having been implicitly loaded before our
modules are compiled.

Explicitly stating in our modules that the variables are dynamic
prevents that.
 2020-10-30 14:23:53 +08:00
Jethro Kuan
0d235686f4 (fix): fix id-face killing buffers (#1218) 
org-roam-id-get-file no longer falls back onto the current buffer: It queries the org-roam database, and optionally org-id-locations, and declares that it does not exist if it isn't in either.
 2020-10-27 00:25:39 +08:00
Kang Yuxuan
ac2044b84b (fix): save current position in mark ring before id-open (#1217) 2020-10-26 13:36:35 +08:00
Herbert Jones
cffa0bd201 (fix): support multidir with dirty db flag (#1216) 2020-10-26 11:22:40 +08:00
Jethro Kuan
bd8b5587f5 (internal): rename link columns (#1213) 
from -> source
to -> dest

"from" is a reserved keyword in sqlite, so we avoid it.
 2020-10-25 22:33:43 +08:00
Jethro Kuan
b937bc9655 (internal): simplify db update operations (#1212) 
Instead of maintaining a file queue to process for updating the Org-roam
database, we instead simply call `org-roam-db-build-cache` to rebuild
the db. `org-roam-db-build-cache` feels Fast Enough(TM), and basically
runs instantly if no files are modified. This greatly simplifies the
code, basically allowing to maintaining a single code path for db
operations.

This PR should also address the slowness wrt to ID links. Org-roam now
builds the headline information first, so there is no need to read the
file to check if the headline is there. The downside to this is that
this only works for IDs in Org-roam files.
 2020-10-25 16:35:05 +08:00
Jethro Kuan
a7cf48ea89 (fix): org-roam-db-build-cache: fix order of processing (#1201) 
* (fix): org-roam-db-build-cache: fix order of processing

Org-roam used to perform the removal of deleted files towards the end.
This can cause some issues with db rebuilds. Consider this scenario:

1. Create a file `foo.org` with `id:abc`
2. Run `org-roam-db-build-cache`
3. Delete `foo.org`
4. Create a file `bar.org` with `id:abc`
5. Run `org-roam-db-build-cache`

Here Org-roam will complain that the id `abc` is a duplicate, and error
out, because the data for `foo.org` has not yet been cleared from the
database. This PR reorders the db creation steps the following way:

1. Figure out which files no longer exist, and which files are modified
2. Clear the database for these files, leaving only files that are
unmodified in the database
3. Insert new data from modified files into the database
 2020-10-19 22:12:34 +08:00
Gustav
46327991ef (fix): let-bind org-roam-last-window (#1198) (#1200) 
* org-roam-buffer.el (org-roam-buffer--find-file): Make
org-roam-buffer--find-file insensitive to mutation of global
variables
 2020-10-19 21:14:55 +08:00
Jethro Kuan
a4da8f32bf (fix): use org-roam-link-title-format in link replacement (#1199) 
* (fix): use org-roam-link-title-format in link replacement

Makes `org-roam-format-link` respect `org-roam-link-title-format`.

Also removes lowercasing via prefix argument in `org-roam-insert`, not
sure how many people use it.

* update changelog
 2020-10-19 21:02:25 +08:00
Jethro Kuan
5d483f2d4d (fix): fall back to org-id search ID face computation (#1195) 
* (fix): fall back to org-id search ID face computation

Fixes the scenario where the face is reported as invalid although it is
part of Org's ID files (e.g. in the agenda).

Fixes #1191.

This can however slow face computation a lot (when there are many org
id/agenda files). Here, we choose to focus on correctness.

* Document faces, default to only applying to Org-roam notes
 2020-10-19 13:47:07 +08:00
Boris Buliga
09fd41ce24 (fix): do not kill temp buffer when extracting links for file (#1193) 
Otherwise it breaks `org-roam-db-build-cache` as it relies on temporary buffer.
Without keeping the buffer, `org-roam--extract-links` kills it and any further
functionality of file processing breaks.
 2020-10-19 12:12:36 +08:00
Herbert Jones
a0c4abf579 (fix): allow title changes that don't modify filename (#1189) 
Prevent error when trying to move file to same name

Prevent string matching in org from messing with the current re-search-forward
position which has caused infinite broken search
 2020-10-16 02:19:15 +08:00
Jethro Kuan
cbf1b585ac (doc): fix org-roam-buffer-window-parameters documentation (#1190) 
Closes #1188
 2020-10-16 00:23:47 +08:00
Jethro Kuan
66cd5b6226 (internal): simplify internal db cache update api (#1186) 2020-10-12 21:55:32 +08:00
Boris Buliga
5348654a7e (feat): add interactive functions for managing aliases and tags (#1183) 2020-10-12 14:51:10 +08:00
Jethro Kuan
87d7c07e87 (fix): correct usage of org-element api (#1181) 
content-end -> contents-end
 2020-10-11 14:52:27 +08:00
Jethro Kuan
02fda3adb1 (docs): document org-roam-buffer-window-parameters (#1180) 
also remove documentation on deprecated variable ~org-roam-buffer-no-delete-other-windows~
 2020-10-10 22:28:29 +08:00
Jethro Kuan
82bd6c6cda (fix): fix org-roam--extract-links (#1179) 
Co-authored-by: Boris Buliga <boris@d12frosted.io>
Co-authored-by: Gustav <gustav@whil.se>
 2020-10-10 21:34:16 +08:00
Gustav
e8d3516fa8 (fix): fix org-roam--extract-ids at outline level 0 (#1174) 2020-10-09 22:00:58 +08:00
Jethro Kuan
0cce9d1165 (release): Org-roam v1.2.2 (#1168) 2020-10-06 03:02:41 +08:00
Jethro Kuan
7a76f7b476 (internal): remove compat functions (#1167) 
* remove org-roam-link-make-string
* remove org-roam-link-store-props and org-roam-link-decode
 2020-10-06 02:45:59 +08:00
Jethro Kuan
ceee2348e0 (fix): fix [[*]] completion (#1166) 
Links now complete to [[roam:*foo]] rather than the incorrect [[*roam:foo]]
 2020-10-05 23:24:32 +08:00
Jethro Kuan
32bf91077e (internal): move org-roam.db default location (#1164) 
Move the default location of `org-roam.db` to the user's Emacs
directory. This is a more sensible default: those who sync their
Org files would not have the database synced over as well.
 2020-10-05 18:56:28 +08:00
Jethro Kuan
d973e8f6e0 (feat): support file-level IDs (#1163) 
Additionally cache IDs at outline-level 0, now that property drawers are supported in Org 9.4.

Update org-roam--format-link to prefer ID links wherever possible. That is, when a file has an ID, use an id link instead of file link.
 2020-10-05 16:57:54 +08:00
Jethro Kuan
6759bee56b (doc): add FAQ for completion into manual (#1161) 
Fixes #960
 2020-10-01 12:30:05 +08:00
Jethro Kuan
ce17e7eecd (fix): fix buffer ref-links (#1160) 
remove stray `(org-roam-link-make-string)` call
 2020-10-01 11:21:09 +08:00
Jethro Kuan
369753c98b (feat): clean up link expansions (#1157) 
Adds `org-roam-link-file-path-type`, used for link path computation
wherever sensible. This includes in the org-roam backlinks buffer, and
in link replacement.

Also moves link expansion/fixing from cache build to Org-roam buffer
render time. This reduces cache build time, but makes buffer rendering
slightly slower.
 2020-09-30 19:21:02 +08:00
Jethro Kuan
93d8c477fe (feat): remove file store-link function override (#1155) 
Previously we had overwritten the Org's store link function for files,
to create IDs if the point was under the headline. This has several
issues:

1. It becomes impossible to store a link to the file using `org-store-link`
2. This override is global across Org, although we had a guard in
`org-roam-store-link`
3. IDs are created during an org-capture, because org-capture calls `org-store-link`

This is unnecessary. Org provides `org-id-store-link` instead for this
purpose. Instead, we advice `org-id-new`, to queue the file for a DB
update if an ID was created.
 2020-09-30 15:27:25 +08:00
Jethro Kuan
30d52e5508 (fix): fix org-roam-id-find buffer-kill logic (#1154) 2020-09-30 13:26:14 +08:00
Natnael Kahssay
19c5e9b0f3 (fix): pass file name to extract-headlines. (#1153) 
Another location where filename needs to be passed down as per #1150.
 2020-09-30 11:57:07 +08:00
Jürgen Hötzel
3ec2ed8874 (perf): disable org-agenda while building the cache (#1147) 
`org-mode` builds the org-agenda-files menu entry for every file
visited. This functionality isn't required and useful when building
the cache in temporary org buffers.
 2020-09-29 15:51:12 +08:00
Jethro Kuan
be64f107e9 (internal): replace find-file-noselect with with-temp-buffer where possible (#1150) 
`find-file-noselect` is affected by the user's init.el, and there is
little control over what is being activated. For database updates, read
access is all we need, so we use `with-temp-file`.
 2020-09-29 12:42:23 +08:00
Jethro Kuan
64d8ba1900 (fix): fix org-roam-completions-everywhere (#1145) 
Fix org-roam-completion-everywhere still producing fuzzy links
 2020-09-27 15:51:26 +08:00
Jethro Kuan
2f4034cebc (docs): add docs for Org-roam unlinked references (#1144) 2020-09-27 15:21:49 +08:00
Jethro Kuan
668f135aa1 (internal): remove file-name and header default (#1143) 2020-09-27 04:29:10 +08:00
Jethro Kuan
273d0dffa6 (fix): fix refs not showing in backlinks buffer (#1140) 
This changes ref extraction to parse the ref using the org plain-links
syntax. This works for arbitrary `cite` links, and web links.

Link storage and ref lookup is now based on the path (e.g.
`//google.com`) or `author_year`.
 2020-09-27 02:20:23 +08:00
Jethro Kuan
fadb515a87 (fix): fix emacsql-sqlite3 check (#1142) 2020-09-27 02:14:27 +08:00
Jethro Kuan
2e58d3df19 (fix): add emacsql-sqlite3-executable null check (#1139) 
Fixes #1138
 2020-09-26 20:39:58 +08:00
Natnael Kahssay
c05368a16b (fix): prevent link-extraction from keeping buffers open (#1131) 
Fixes #1129 .

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-09-26 19:42:59 +08:00
Noboru Ota
346bbf50a1 (feat): enable completions for both roam and fuzzy links (#1133) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-09-26 18:05:13 +08:00
Tyler Smith
176b2bf19d (docs): add git installation instructions (#1136) 2020-09-26 13:55:59 +08:00
Jethro Kuan
ae32c465de (feat): move fuzzy links to roam: links (#1105) 2020-09-23 17:58:18 +08:00
Jethro Kuan
da6af3a468 (fix): fix additional buffers opening from ID face (#1130) 
`org-roam-id-find` opens the file containing the ID to get the marker.
We don't need to get the exact point for face computation.

Fixes #1129
 2020-09-23 13:09:16 +08:00
Jethro Kuan
cd87cfdd58 (perf): simplify hash computation (#1127) 
Treat encrypted and non-encrypted files the same.
 2020-09-22 20:35:48 +08:00
carlos
feda1f41e5 (feat): extract idle timer interval as a customizable value (#1122) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-09-22 15:10:43 +08:00
Jethro Kuan
d170c4ac85 (fix): remove other occurrences of file-truename (#1125) 
org-roam-buffer should no longer be resolving the symlinks as well.
 2020-09-22 14:23:02 +08:00
Geoff Langenderfer
f59c18fda5 (docs): update org-roam-graph-show in README.md (#1121) 2020-09-20 17:11:40 +08:00
Jethro Kuan
f5257cefa7 (ci): make CI pass on non-blocking errors (#1117) 2020-09-19 16:45:38 +08:00
Jethro Kuan
18c0f2da7f (ci): do not return on package-lint error (#1116) 2020-09-19 16:23:09 +08:00
Kisaragi Hiu
b2aa8bdad0 (feat): remove all symlink resolutions (#1109) 
file-truename calls alone accounts for over 20% of CPU samples in org-roam-db-build-cache. It's expensive and unnecessary. To get an absolute path, expand-file-name alone is enough.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-09-19 16:12:08 +08:00
Jethro Kuan
925d225f13 (fix): fix file-name change not working on new files (#1113) 
PR #1076 prevented the title change hook from causing errors for new files,
but completely disables the behaviour. To cause the title hooks to take
effect, we set the local variable `org-roam-current-title` upon save,
regardless of whether the hook ran.

This should have the effect of enabling the title change behaviour upon
first save, assuming the save succeeds.

Addresses https://org-roam.discourse.group/t/org-roam-update-file-name-on-title-change-works-discontinuously/767
 2020-09-18 14:52:51 +08:00
Jethro Kuan
6c89eb82af (fix): perform link expansion only on file links (#1110) 
This prevents ID links from being expanded in the Org-roam buffer
 2020-09-17 14:29:40 +08:00
Jethro Kuan
8ec4cafa2b (fix): fix link expansion on URL links (#1103) 
Attempting to perform link expansion on URL links caused extreme slowdowns in Windows environment. Ref #1038 #1067.

Co-authored-by: Noboru Ota <me@nobiot.com>
 2020-09-17 13:28:42 +08:00
Jethro Kuan
e881ea26b1 (internal): bump required version of emacsql-sqlite3 to 1.0.2 (#1102) 
This version includes the fix that ignores the user .sqliterc which can
interfere with expected behaviour.

See https://github.com/cireu/emacsql-sqlite3/pull/15 for more details.
 2020-09-15 15:10:36 +08:00
Jethro Kuan
efb592907e (fix): fix org-agenda hangs on face computation (#1101) 
Org expects face functions to save-match-data, or it would lead to
infinite recursions with use of some Org functionality such as
org-agenda (h.t. @myshevchuk for figuring this out)

Fixes #1096 and fixes #1045.
 2020-09-13 20:42:28 +08:00
Jethro Kuan
da507a5bee (fix): add vanilla option for tag custom interface (#1100) 2020-09-13 02:56:32 +08:00
Sophie Taylor
fc3a03977d (feat): add vanilla org-mode-tag-source (#1093) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-09-13 02:45:45 +08:00
Richard Kim
70539c40d2 (fix): fix backlinks in org-roam buffer (#1099) 
previously when the file is a symbolic link, the backlinks buffer display will not show correctly.
 2020-09-13 01:48:07 +08:00
Jethro Kuan
fac0465dd8 (feat): add org-roam-enable-fuzzy-links (#1097) 
`org-roam-enable-fuzzy-links` controls whether to enable Org-roam's
fuzzy link behaviour. This can be undesirable to some users, who would
like to use [[foo]] links to reference named blocks
 2020-09-12 19:30:05 +08:00
Jethro Kuan
6d09323218 (fix): fix sort by mtime in completions (#1087) 2020-09-07 10:14:49 +08:00
Jethro Kuan
e3ff54616e (feat): sort backlinks by occurrence (#1086) 
Sort display of backlinks in backlinks buffer by occurrence. The default
link extraction behaviour causes it to be inserted roughly in the
reverse order.
 2020-09-04 21:05:49 +08:00
Jethro Kuan
d3a920a5b7 (fix): fix link outline extraction (#1085) 2020-09-04 20:37:02 +08:00
Jethro Kuan
8fff0b86f9 (fix): fix link-extraction extracting wrong element (#1084) 
Fixes #1082, #1077, #1074

When reverting link extraction to using the `org-element` api, the
preview content (org-element-at-point) was incorrectly extracted,
causing incorrect preview content and cryptic messages.
 2020-09-04 15:09:12 +08:00
Kisaragi Hiu
df174bb52b Fix link extraction error when a file starts with blank lines (#1081) 
org-element-at-point doesn't just determine the closest element -- if
it's "within blank lines at the beginning of buffer", it returns nil.

  ;; Within blank lines at the beginning of buffer, return nil.
  ((bobp) nil)

Skip whitespace at beginning of buffer to avoid this.
 2020-09-03 10:02:10 +08:00
Jethro Kuan
cb10b16fc0 (feat): add org-roam-tag-face (#1079) 
`org-roam-tag-face` controls the appearance of tags in the minibuffer.
Defaults to a bold face.
 2020-08-31 23:02:12 +08:00
Sławomir Żak
9ff57c8fd1 (fix): don't run title-change-hooks on new files (#1076) 2020-08-30 02:16:13 +08:00
Jethro Kuan
a6aabf4038 (feat): rename file on title change (#1073) 
Adds `org-roam-title-change-hook`. This now contains two functions:

1. `org-roam--update-links-on-title-change`: updates the link
description of all files that link to the current file.
2. `org-roam--update-file-name-on-title-change`: updates the current
buffer's filename to reflect the updated title.
 2020-08-27 22:13:23 +08:00
Jethro Kuan
f8c8fcee6b (test): reduce expected cache time-to-build (#1072) 
Several performance improvements have vastly improved the cache build
time. We reduce it so CI catches any further degradation.
 2020-08-27 13:23:58 +08:00
Tim Quelch
6f0a38e64e (feat): disable unnecessary org-mode startup for temp buffers (#1057) 
Set `org-inhibit-startup` to `t` to reduce the amount of time taken to set up org-mode buffers. For example, this disables latex image generation, and table alignment.

Also introduces `org-roam-doctor-inhibit-startup`, which speeds up `org-roam-doctor` runs.
 2020-08-27 13:23:38 +08:00
Jethro Kuan
b8b180d60d (feat): rename link descriptions on title changes (#1071) 
Previously the rename file advice was responsible for trying to update
the link descriptions as well. This was brittle and didn't work in some
cases.

The rename-file-advice has now been altered to solely deal with breaking
links. We use the before and after-save-hooks to determine whether the
title has changed, and update the link descriptions accordingly.
 2020-08-26 17:24:58 +08:00
Jethro Kuan
fe5566c0dc (fix): fix non-fuzzy links being treated as fuzzy links (#1070) 
Fuzzy links were initially detected as anything within double brackets.
This could include code in source blocks.

This PR introduces `(org-roam--fuzzy-link-p)`. This uses an additional
check using the `org-element` API, and ensures that the link type is
fuzzy (not a file: or https: link, for example).

Fixes #1069, and an array of unreported bugs:

1. Link extraction into the database should no longer pick up false
links (in code blocks, for example).
2. Link completion will only truly work within fuzzy links
 2020-08-26 15:27:45 +08:00
Jethro Kuan
cc8a2184b7 (internal): replace org-element-parse-buffer calls with regexp search (#1068) 2020-08-26 13:44:35 +08:00
Jethro Kuan
4f0b1b8d43 (internal): use regexp search for link-extraction (#1066) 
Replace call to org-element-parse-buffer with simple regexp search.
 2020-08-25 18:24:29 +08:00
Jethro Kuan
0a64a5def4 (feat): allow enabling of link completions everywhere (#1062) 
Completions for Org-roam files can be enabled everywhere by setting
`org-roam-completion-everywhere` to `t`.
 2020-08-25 17:09:10 +08:00
Jethro Kuan
2cd993e0a5 (internal): use regexp-search for fuzzy link replacement (#1065) 
This should improve responsiveness on large files
 2020-08-25 13:57:02 +08:00
Kisaragi Hiu
82ac6b6b9c (internal): speed up extraction of global props, headlines, and title (#1061) 
Avoids usage of org-element-parse-buffer, preferring simple regex searches.
 2020-08-24 22:14:15 +08:00
Jethro Kuan
f6bf9d9401 (fix): remove org-roam-completion-case-sensitive (#1060) 
Case sensitivity for completions is already controlled via
`completion-ignore-case`, so we remove this variable that doesn't
actually do what is expected.
 2020-08-24 16:59:53 +08:00
Jethro Kuan
38234b491d (feat): add case sensitivity for Org-roam completions (#1056) 
Completions are now case-insensitive by default.
`org-roam-completion-case-sensitive` can be set to `t` to allow
case-sensitive completions.
 2020-08-22 20:21:01 +08:00
Jethro Kuan
4e5b52fbd3 (fix) strip todo, priority, and tags from headline candidates (#1052) 
Fixes #1047
 2020-08-20 15:01:19 +08:00
Kisaragi Hiu
c33867e6bc (feat): allow ignoring files matching a regular expression (#1046) 
Adds a new user option, `org-roam-file-exclude-regexp`, to exclude files from Org-roam.
 2020-08-18 16:16:56 +08:00
lld2001
30b2e97426 (feat): add org-capture interactive options to org-roam-capture (#1035) 2020-08-16 19:51:37 +08:00
Jethro Kuan
9ee591f7a4 (fix): fix possibility of multiple idle timers (#1042) 
This change ensures that `org-roam--file-update-timer` has only one
instance per Emacs instance. Fixes #1037
 2020-08-16 12:08:19 +08:00
Charl P. Botha
2081e1268a (feat): add org-roam-enable-headline-linking (#1030) 
When disabled, Org-roam will not attempt to cache headlines, and will not create IDs.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-08-13 11:18:06 +08:00
Charl P. Botha
11aac39a1b (feat): propagate file changes on idle-timer (#1032) 
Queue up file updates, to be processed on idle timer. This makes saving files more responsive for large files.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-08-12 17:07:27 +08:00
Simon Manning
e58ec84b7c (fix): Require org-macs in org-roam-db to fix undefined macro (#1033) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-08-11 21:22:54 +02:00
Jethro Kuan
7813b1fe1f (internal): fix CI for compat functions (#1031) 
Following the advice from the coding conventions from the Emacs manual,
we preface the compatibility functions with the org-roam namespace.
 2020-08-12 00:04:15 +08:00
Jethro Kuan
22006be751 (docs): set org-roam-db-location with multiple org-roam-directories (#1027) 
Fixes #1025
 2020-08-11 13:51:29 +08:00
odomanov
0318983cac (feat): cache all link-types (#1009) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-08-10 15:59:02 +08:00
Jethro Kuan
9753ee451f (fix): fix fuzzy link completions (#1022) 2020-08-10 15:38:17 +08:00
Jethro Kuan
8c442a72de (fix): fix fuzzy-links opening for file (#1023) 2020-08-10 14:31:10 +08:00
Jethro Kuan
0ed9057a87 (feat): tag completion via capf (#1017) 2020-08-09 21:49:06 +08:00
Jethro Kuan
5d02e6407b (fix): remove save-buffer on id creation (#1018) 
This can trigger a lot of hooks, which may not be desirable.
 2020-08-09 21:03:27 +08:00
Jethro Kuan
4fa966d366 (feat): fuzzy link auto-replacement (#1011) 
Fuzzy links can now be auto-replaced on navigation and on file-save, if
there is already a match. This is now the default behaviour, controlled
via `org-roam-auto-replace-fuzzy-links`.
 2020-08-09 12:20:02 +08:00
Jethro Kuan
6d03e7626d (fix): save-restriction for db update (#1016) 2020-08-09 12:06:34 +08:00
Leon
c437052b4b (docs): update url of org-fc (#1012) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-08-09 11:55:07 +08:00
Leo Vivier
a26c262048 (fix): Widen before updating file (#1014) 2020-08-09 00:24:12 +02:00
Jethro Kuan
4f3668a1e3 (fix): fix get-backlinks failing for unescaped strings (#1008) 
Revert to emacsql vector format to retain escaping. Fixes #1007.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-08-07 16:06:24 +08:00
Jethro Kuan
09b5357a94 (docs): remove readthedocs build (#1006) 
This has long been superceded by the internal and published online manual
 2020-08-06 11:15:14 +08:00
Jethro Kuan
444eedc799 (internal): remove with-template-error wrapper (#1004) 
This has caused more confusion than it has helped.
 2020-08-06 10:51:24 +08:00
Jethro Kuan
da6fdd7542 (feat): support fuzzy links (#910) 2020-08-05 20:52:27 +08:00
Leo Vivier
f18ecd1fc3 (feat): Implement new face-toggle for id-links (#999) 
Also fix a typo.
 2020-08-04 15:26:51 +02:00
targit
f206b5bbf9 (fix): skip unreadable files while building the cache (#995) 
When using gpg encrypted files it might happen (intended) that on a
certain machine there is no key to decrypt that file.  Currently an
error of type 'file-error' will be raised and the cache building
process will be aborted.  So in a certain sense org-roam will not
be functional in that case.  Furthermore, when the the cache building
process is run from the emacs initialisation it will come to a halt as
well and the user will be left with a halfworking emacs instance.

This patch changes the behaviour to just skipping over offending files
while removing them from the db at the same time.  Here an offending
file is any file that cannot be read for indexing.  As it stands this
case only works reliably for the case of missing gpg keys.

An error buffer will still show up and be prominently displayed,
besides a log to the message buffer.

Implementation note: This io error will only be caught during the
first part of the cache rebuilding ("files and headlines").  If such
an error would occur during the second part ("rebuild the rest")
another (more severe) cause might be the problem and the user better
be informed the hard way (i.e. the same behaviour as before).
 2020-08-03 16:58:22 +08:00
Leo Vivier
30fab7bcc4 (feat): Add toggle for custom-faces for Org-roam links (#997) 
* org-roam.el (org-roam-link-use-custom-faces): New toggle
(org-roam--file-link-face): Refactor for new toggle
 2020-08-02 18:27:38 +02:00
Leo Vivier
76d2e3f6b4 (feat): Simplify org-roam-store-link (#994) 
* (feat): Simplify org-roam-store-link

Drop the wrapper, and refactor as an org-store-link function.
 2020-08-01 08:02:57 +02:00
Daniel Gomez
8881c9732b (fix) Change Emacs date to 1976 (#993) 
cf. https://en.wikipedia.org/wiki/Emacs
 2020-07-31 15:29:59 +02:00
Jethro Kuan
0aa0a7c05a (doc): Add target audience section (#990) 2020-07-31 02:15:42 +08:00
Jethro Kuan
ea4bfbb55d (fix): fix face-related functionality (#988) 
- Ensure `org-roam-store-link-file` has no effect if org-roam-mode is
disabled
- Remove custom styling for ID links when org-roam-mode is disabled
 2020-07-30 09:56:13 +08:00
Jethro Kuan
0443351800 (internal): move faces into own file (#987) 2020-07-30 09:12:56 +08:00
Leo Vivier
6345d0c22e (feat): Protect region targeted by org-roam-insert (#974) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-07-27 20:16:39 +02:00
Leo Vivier
f2c1500beb (doc): Fix docstring (#979) 2020-07-27 11:43:23 +02:00
Jethro Kuan
89e9121f26 (release): Org-roam v1.2.1 (#975) 2020-07-27 01:03:35 +08:00
Mykhailo Shevchuk
c536fd4f2e (fix): check if path is remote before using file-truename (#970) 
this prevents cache builds from stalling, on paths that point to remote files
 2020-07-27 00:30:54 +08:00
Jethro Kuan
20f876aa6b (feat): enable nested captures (#966) 
This PR enables the long-awaited nested-captures.

1. Adds a hook to org-capture-prepare-finalize-hook, which installs org-roam-capture--finalize into org-capture-after-finalize-hook if the capture is an Org-roam capture. This function contains key functionality for Org-roam to Do The Right Thing after specific interactive functions, such as finding the file, or inserting a link.

2. A patch for org-capture-finalize. Specifically, we make org-capture-plist valid during org-capture-finalize.

3. Many hacks that were originally in place are now replaced with nicer alternatives.

Co-authored-by: Leo Vivier <zaephon@gmail.com>
 2020-07-27 00:21:41 +08:00
Mykhailo Shevchuk
863ae2427e (feat): add customize settings for capture templates (#968) 
adds ability to customize capture templates using the Customize interface for:

1. org-roam-capture-ref-templates
2. org-roam-dailies-capture-templates
3. org-roam-capture-immediate-template
 2020-07-26 15:15:56 +08:00
Jethro Kuan
379d5e4770 (doc): Add Andreas to backers (#969) 2020-07-25 16:33:36 +08:00
Jethro Kuan
4d992ce9e3 (doc): add debian/ubuntu installation instructions (#965) 
Addresses #964
 2020-07-23 22:46:21 +08:00
targit
1d9968bf69 Make the db caching more efficient for gpg encrypted files (#963) 
Before this patch all hash-sums were computed over the files or
buffers content.  For encrypted files this means that we first have
decrypt the file before we can compute the hash-sum.  So when the
cache get's updated all gpg files need to be decrypted which is a very
expensive operation and nearly defeats the purpose of having a cache
in the first place (for gpg files).

This changes the computation of hash-sums for gpg encrypted files.
Instead of the content the raw files on disk will be read.

This shouldn't interfere with the current use of hashes.

There is one ugly (but otherwise inconsequential) ward, though.
For open buffers of to be gpg encrypted files we need to compute the
hash sum over the contents as well.  This is because there is
no (easy) way to get the encrypted version.  The consequence is that
that buffers file will be rehashed again (then using the bytes on
disk).  But all other non changed gpg files will only be hashed once,
as desired.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-07-23 22:36:57 +08:00
Leo Vivier
650744adc7 (doc): Create ‘Getting Help’ (#961) 
* (doc): Create ‘Getting Help’

* README.md: Add ‘Getting Help’

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-07-22 19:06:54 +02:00
Jethro Kuan
d099f9bef9 (fix): enable org-mode in temp buffers (#957) 
Fixes #956.

The extraction of links rely on appropriate regexp being set for
outline-mode, to determine the outline information. Because the
information were extracted in a temporary buffer, the outline regexp was
not set. This corrects for that, but probably adds significant
extraction time.
 2020-07-22 20:59:35 +08:00
Leo Vivier
b5f3f04318 (doc): Add an FAQ section (#959) 
* README.md: Create FAQ section and mention `C-M-j` for `ivy`
 2020-07-22 09:07:49 +02:00
endgame
c20c8f9a0a (fix): Check sqlite3’s executability using boundp (#954) 
Fixes #837. The existing merged fixes do not actually work, because fboundp tests for a function.
 2020-07-21 15:51:43 +08:00
Jethro Kuan
c24fb51b03 (feat): cache entered template variables (#952) 
Fixes #951.
 2020-07-20 22:14:21 +08:00
Jethro Kuan
80390b5a84 (fix): fix display of preview content (#950) 
Don't modify line-breaks in preview content. Closes #630.
 2020-07-19 13:33:01 +08:00
Jethro Kuan
eb7ee0ef6c (docs): add docs on notes versioning (#949) 2020-07-19 12:37:53 +08:00
Jethro Kuan
fb5beeb14d (docs): clarify org-roam-completion-system (#948) 2020-07-19 12:26:00 +08:00
Jethro Kuan
10e91a88c1 (docs): make explicit need to set org-roam-directory early (#946) 2020-07-18 18:04:52 +08:00
Jethro Kuan
4cdab9103f (fix): fix possible nil dbs on update operations (#945) 
Addresses #942
 2020-07-18 13:09:40 +08:00
Leo Vivier
4ec4e60358 (doc): Add SVG source for logo (#943) 2020-07-16 10:20:42 +02:00
Leo Vivier
7a4b15fd36 (fix): Check if link-description is empty prior to inserting in db (#927) 
* (fix): Check if link-description is empty prior to inserting in db

Caused problems with plain links, i.e., those not framed by
brackets (e.g. `file:foo.org` or `id:$uuid`).
 2020-07-11 23:42:05 +02:00
Mykhailo Shevchuk
f9fea29c44 (feat): Add customize settings to org-roam-capture-templates (#924) 
* (feat): Add customize settings to `org-roam-capture-templates`

Declare `org-roam-capture-templates` with `defcustom` and update the
docstring.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-07-11 20:48:10 +02:00
Leo Vivier
569aeb84ed (fix): Change symbol used for delta (#925) 
7f56df7f4d introduced the delta symbol in the
db-rebuild message to make it clearer the the db was updated as opposed to
being completely rebuilt.

However, the unicode symbol used, U+1D6AB, which is the mathematical, bold
variant of the Greek letter is not present in many fonts.  Switching to
U+0394, the base Greek letter, is better for compatibility.
 2020-07-11 20:19:55 +02:00
Matthew Ryall
1574e0d351 Exclude backup files from renaming advice (#915) 
Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-07-10 23:18:33 +02:00
Leo Vivier
fffef6711f (fix): Update rename-file-advice to new schemata (#917) 
Caused by #908.
 2020-07-10 19:59:07 +02:00
Leo Vivier
ef23f507ec (fix): Adapt get-title-or-slug to new schemata (#916) 
Follow-up to #908.
 2020-07-10 19:34:12 +02:00
Jethro Kuan
f1dbe3fdf9 (fix): fix org-roam graph building with new db schema (#914) 2020-07-10 19:23:38 +08:00
Jethro Kuan
efba3c2bf0 (internal): normalize titles in database (#908) 
Instead of storing titles as a list within in the Org-roam cache, e.g.
file, ("title1" "title2"). We normalize it and store it as:

file, "title1"
file, "title2"
 2020-07-10 14:36:54 +08:00
Leo Vivier
6770c3eaf5 (feat): Implement basic output for find-ref with C-u arg (#907) 2020-07-10 08:24:04 +02:00
Leo Vivier
b8aa5c1f23 (feat): Improve interactive format for ref completions (#906) 2020-07-10 11:47:07 +08:00
Jethro Kuan
ca4a7421bc (docs): Update org-roam-capture documentation (#904) 2020-07-09 12:56:17 +08:00
Jethro Kuan
3348298527 (internal): org-roam-db--clear -> org-roam-db-clear (#902) 
Since it is a called interactive, it should be given a public name.
 2020-07-08 15:55:23 +08:00
Jethro Kuan
d77f897400 (feat): support more ref links (#900) 
This adds support for all sorts of ref links (http, https, and any
custom link types). If the ref is not a file or org-ref citation link,
the full link path is used.

Closes #744.
 2020-07-08 12:29:06 +08:00
Jethro Kuan
9f7ed4353c (feat): add org-roam-random-note (#898) 2020-07-07 14:45:28 +08:00
Jethro Kuan
d19a711a44 (fix): fix escaping of backslashes in graph generation (#897) 
Fixes #884
 2020-07-07 13:07:10 +08:00
Jethro Kuan
9766862e84 (docs): Add forkrul to BACKERS (#896) 2020-07-07 12:36:27 +08:00
Jethro Kuan
aedfca8de2 (fix): rename links as long as old file is Org-roam file (#894) 
Previously, if the new file is no longer an Org-roam file, links will
not be fixed. The current behaviour is now to perform the link fixes as
long as the old file as an Org-roam file.

Closes #893
 2020-07-06 21:34:52 +08:00
Jethro Kuan
21bc220ed3 (docs): fix qutebrowser roam-protocol binding (#891) 2020-07-06 11:39:11 +08:00
Jethro Kuan
d58fc31dfb (docs): add docs for using winner-mode as history (#890) 2020-07-05 23:07:41 +08:00
Jethro Kuan
64a0bfd168 (docs): add Burke to BACKERS (#889) 2020-07-05 22:43:13 +08:00
Herbert Jones
3aff6b2be7 (bugfix): prevent file-exists-p opening tramp links (#885) 
Links like /ssh:me@host:/ cause emacs to lock up asking for the password repeatedly due to using file-exists-p in a function passed to font lock.

Co-authored-by: Herbert Jones <herbert@hj-desktop.home>
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-07-05 22:36:35 +08:00
Jethro Kuan
7f56df7f4d (internal): add delta symbol in cache build message (#886) 
This makes it clearer that the message shows the changes in the database, and not the total number.
 2020-07-05 17:48:17 +08:00
Jethro Kuan
0830da4504 (tests): increase perf test threshold (#887) 
Things take more time to run now that we are also caching headline hierarchies.
 2020-07-05 17:36:44 +08:00
karamme
3a1c826aa0 (docs): add protocol instructions for Windows and WSL2 (#882) 
See #870
 2020-07-04 00:25:23 +08:00
Mohsin Kaleem
1e11a3a16f (feat): add customizable org-capture function (#877) 
New option: `org-roam-capture-function`

Specifies which command is used by org-roam to run the org-capture
process. The default behaviour maintains compatibility with earlier
versions of org-roam. I.E.:
- uses `org-capture`.
- immeadiately chooses the first capture template when
  `org-roam-capture-templates` has only one template.

When you've changed `org-roam-capture-function` AND
`org-roam-capture-templates` has multiple templates,
`org-roam-capture-function` is run interactively to
start the org capture process.

Eg. usage: `(setq org-roam-capture-function 'counsel-org-capture)`
 2020-07-01 23:24:40 +08:00
Jethro Kuan
e33c3bcb3f (internal): lower default value of org-roam-db-gc-threshold (#872) 
The high value has been reported to cause significant slowdowns, so we
reset the default, and add documentation for its customization instead.
Ref #834
 2020-06-28 15:16:14 +08:00
Jethro Kuan
610d4ced85 (internal): save-match-data on outline extraction (#871) 2020-06-27 21:26:03 +08:00
Jethro Kuan
2f13d1fe64 (internal): fix expand-file usage in org-roam--expand-links (#866) 2020-06-26 14:57:27 +08:00
Sibi Prabakaran
ee28b5e6b1 (docs): improve roam-ref docs (#865) 
The current documentation made me think that bookmarklet feature was limited to Firefox. This patch slightly improves it.
 2020-06-26 14:52:08 +08:00
Jethro Kuan
79c75ac174 (feat): Add header level to backlinks buffer (#863) 
adds the outline hierarchy to the backlinks buffer
 2020-06-25 12:40:22 +08:00
Tim Quelch
c59d6c4f7c (internal): wrap db updates in a sql transaction (#862) 
This will ensure atomicity with updates and should stop any partial updates that may occur.
 2020-06-24 13:30:44 +08:00
Jethro Kuan
220f395c1f (feat): add org-roam-find-file-immediate (#852) 
Addresses #852.
 2020-06-22 16:19:27 +08:00
Jethro Kuan
76b2ac3460 (bugfix): fix tag extraction for symlinked directories (#857) 
* (bugfix): fix tag extraction for symlinked directories

Resolves symlinks before computing relative paths, fixes #855

* Update changelog
 2020-06-21 19:34:04 +08:00
Jethro Kuan
11e0aa4c55 (feat): warn on duplicate IDs and refs rather than fail (#854) 
Instead of having db update operations fail, a useful error is shown, and the db updates complete. Closes #816.
 2020-06-21 17:00:20 +08:00
Jethro Kuan
408e38f8ba (perf): use sqlite transactions, and GC less (#847) 
We use sqlite transactions to commit changes into the database, rather
than storing all the data in a list before running one big insert.
Hopefully this gives a noticeable perf boost.

We also add `org-roam-db-gc-threshold`, which shaves time by deferring the garbage collection to the end.
 2020-06-19 18:27:14 +08:00
Alexey Shmalko
f16de357a6 (feat): add 'first-directory option for org-roam-tag-sources (#851) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-06-19 18:22:52 +08:00
robert seaton
abd81918e1 (docs): update docs link in README (#850) 
Thanks for the catch!
 2020-06-19 12:04:09 +08:00
Jethro Kuan
6a37fff1e6 (fix): fix bad upcase for org-roam-tag-sources (#849) 2020-06-19 01:58:17 +08:00
Jethro Kuan
527c693f65 (docs): Update links to online page (#848) 
We now own and use the orgroam.com domain
 2020-06-18 19:30:42 +08:00
Jethro Kuan
76d419cc89 (fix): fix emacsql-sqlite3-executable possibly unbound (#846) 
On old versions of emacsql-sqlite3, this will catastrophically fail.
 2020-06-18 14:44:26 +08:00
Stig Brautaset
3f2f7e3ff7 (docs): use org-roam-graph-show on README (#844) 2020-06-18 02:56:25 +08:00
Boris Buliga
fd73da9410 (feat): org-roam-insert: return selected file (#839) 
This is useful in scenarios when you want to automatically do something with the
context where the link was inserted.
 2020-06-17 19:07:35 +08:00
Jethro Kuan
11902bc790 (tests): add performance tests to CI (#841) 2020-06-17 18:38:10 +08:00
Jethro Kuan
185f9877ae (tests): add test for headline extraction (#840) 2020-06-17 15:32:12 +08:00
Zachary
1276e801c0 (feat): add customizable org-roam-title-to-slug-function (#833) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-06-17 14:58:11 +08:00
Leo Vivier
04d335cc40 (fix): Check sqlite3’s executability before existence (#838) 2020-06-17 14:52:26 +08:00
N V
8b16e5d520 (feat): org-roam-find-file-function customization (#807) 
Allow users to specify a function for finding files in various commands.
Can be let-bound to define new commands that suit user preferences.

See: #790
 2020-06-16 15:37:03 +08:00
Leo Vivier
7ab67436a7 (feat): Implement ‘org-roam-insert-immediate’ (#814) 2020-06-15 18:34:27 +08:00
Langston Barrett
87403b330c (feat): Split org-roam-buffer-toggle into -activate and -deactivate (#819) 
Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-06-14 08:12:23 +02:00
N V
fae45434b5 (doc): Add :ensure to use-package declaration (#820) 
Ensure use-package installs org-roam.

See: #803
 2020-06-14 11:58:42 +08:00
Jethro Kuan
9cf26494e8 (ux): update the error message for org-roam-unlinked-references (#818) 
Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
Co-authored-by: Santiago Gepigon <santiago.gepigon@gmail.com>
 2020-06-13 22:33:37 +08:00
Jethro Kuan
0d5efe1c14 (fix): fix unlinked-references for older Emacs (#812) 
Emacs' in-built rx.el was rewritten in Emacs 27, and the form `anychar`
only exists in later versions. We use the older form `anything` that has
support even in Emacs 26.

Emacs 26: https://github.com/emacs-mirror/emacs/blob/emacs-26/lisp/emacs-lisp/rx.el#L889
 2020-06-13 11:14:57 +02:00
Leo Vivier
2eb0aac88a (feat): Switch to a minor-mode for the dev-suite (#805) 
* (feat): Switch to a minor-mode for the dev-suite

Co-authored-by: N V <44036031+progfolio@users.noreply.github.com>

Co-authored-by: N V <44036031+progfolio@users.noreply.github.com>
 2020-06-12 22:01:52 +02:00
Jethro Kuan
eca07277ce (release): Org-roam v1.2.0 (#802) 2020-06-12 23:29:52 +08:00
Jethro Kuan
48158e67d4 (feat): add org-roam-unlinked-references (#787) 
`org-roam-unlinked-references` uses rg to search for unlinked references. Regex courtesy of @angelsl.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-06-12 23:21:01 +08:00
Leo Vivier
278e3df95d (fix): Remove space in docstring (#800) 2020-06-12 13:54:49 +02:00
Leo Vivier
48d2c199ac (fix): Fix local-var loading for dev suite (#799) 2020-06-12 13:49:33 +02:00
Leo Vivier
7f7ba857de (feat): add support for headlines (#783) 
Achieve feature parity between links to files and links to headlines.

Before, we used the `file:foo::*bar` format to link to the headline `bar` in file `foo`, but this was prone to breakage upon renaming the file or modifying the headline. This is not the case anymore. Now, we use `org-id` to create IDs for those headlines, which are then stored in our database to compute the relationships and jump around. Note that this will work even if you’re not using `org-id` in your global configuration for Org-mode.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-06-12 18:51:13 +08:00
Jethro Kuan
cf368ab4d8 (chore): remove unused mkdocs.yml (#798) 2020-06-12 17:47:18 +08:00
Noboru Ota
43dbad1f62 (UX): Add more meaningful error message for sqlite3 (#776) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-06-12 17:14:59 +08:00
Jethro Kuan
040913151f (docs): update docstring for org-roam-db-location (#797) 
Closes #792
 2020-06-12 13:59:25 +08:00
Tim Quelch
1a964520f2 (doc): Add documentation about multiple templates for capture (#796) 
* Add sentence noting that you can have multiple templates

* Add sentence describing that `file-name` can specify directory

* Make changes in .org instead

* Fix grammar and reflow

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-06-12 07:14:09 +02:00
Tim Quelch
39276362d7 (docs): add entries to changelog (#795) 2020-06-12 11:31:06 +08:00
Leo Vivier
1168c9b6da (fix): Fix syntax for calling compiled versions of functions (#791) 2020-06-11 08:39:12 +02:00
Jethro Kuan
92e02b5d14 (internal): remove redundant org-ref require (#788) 2020-06-10 20:02:37 +08:00
Jethro Kuan
26b90b28e3 (fix): fix false failure from case in org-roam-doctor 2020-06-10 18:33:12 +08:00
Jethro Kuan
f4376f39a9 (docs): update roam-ref qutebrowser configuration (#780) 2020-06-09 16:49:11 +08:00
Jethro Kuan
898c6c8178 (docs): Add link to Roam-migration (#779) 2020-06-09 16:11:03 +08:00
Jethro Kuan
30599cc3e8 (fix): fix prop extraction failures (#772) 
This fixes a bug introduced in #770. Interestingly,
`org-element-property` always returns the prop in allcaps, so a
string-equal would have been sufficient. This commit reverts all usages
of `org-roam--extract-global-props` to use the upcase version of the
properties.
 2020-06-07 22:10:47 +08:00
Jethro Kuan
9d5a34d0f4 (internal): lowercase all properties (#770) 2020-06-07 16:25:34 +08:00
N V
5bf3e596c8 (feat): prefer lowercase versions of org in-file settings (#769) 
See #768
 2020-06-07 13:55:07 +08:00
N V
14f83bdb07 (fix): org-roam-capture append to existing file (#767) 
org-roam-capture was querying plist for :file-path
instead of :path.

See: #766
 2020-06-07 13:29:26 +08:00
Jethro Kuan
81e7a5b231 (fix): fix org-roam--list-files elisp fallback (#764) 
Always fallback to the elisp implementation, when the shell commands
return garbage (possibly from shell configurations).
 2020-06-06 19:27:15 +08:00
Jethro Kuan
1756ec6441 (fix): fix bad behaviour on malformed properties (#763) 
Org-roam now skips over bad properties and throws a warning for the
given file that contains a malformed property. This allows most of the
database rebuild to complete, and for the user to fix the offending
file.

Fixes #728.
 2020-06-06 16:48:42 +08:00
Jethro Kuan
c61f7e20f2 (fix): simplify org-roam--str-to-list (#762) 
This simplifies `org-roam--str-to-list`, and ensures that it parses
numbers correctly too. Fixes #745.
 2020-06-05 20:27:02 +08:00
Jethro Kuan
563252a6f6 (fix): remove alias for org-roam-buffer-no-delete-other-windows (#761) 
This variable is made obsolete, and replaced with
`org-roam-buffer-window-parameters`, but their shape are different and
cannot be used interchangeably.
 2020-06-05 15:54:02 +08:00
Tim Quelch
fdaf07da43 (fix): fix update-tags to correct delete removed tags (#760) 
see https://github.com/org-roam/org-roam/pull/759#discussion_r435704588
 2020-06-05 14:33:39 +08:00
Göktuğ Karakaşlı
5d25c4552d (internal): change org-roam-db--update-tags to only add non-nil tags (#759) 2020-06-05 13:36:13 +08:00
Jethro Kuan
c46d153fd3 (internal): Make org-roam-db--get non-interactive (#758) 2020-06-04 22:07:09 +08:00
Jethro Kuan
0cd4bc05c5 (feat): make roam properties case-insensitive (#757) 2020-06-04 16:39:23 +08:00
Jethro Kuan
c5e0c6b9fa (fix): fix bug in org-roam-buffer-get-create (#754) 2020-06-04 12:32:45 +08:00
Jethro Kuan
721689d5b5 (feat): add org-roam-buffer-window-parameters (#750) 
The variable `org-roam-buffer-window-parameters` gives more
flexibility in customizing the org-roam-buffer window parameters.
`org-roam-buffer-no-delete-other-windows` is deprecated in favour of
this.
 2020-06-03 23:25:31 +08:00
Peter J. Jones
d36d3185ae Remove reliance on the current buffer when opening the *org-roam* window (#731) 
If the `org-roam-buffer--get-create' function is called from a hook
then `get-buffer-window' will return `nil' since the current buffer
may not have been placed in a window yet.  This eventually leads to an
error.

This change moves some code around so that we can use
`save-selected-window' to allow temporary focu
s on the org-roam
side window so the resizing functions can work.
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-06-03 21:11:46 +08:00
Lyn Headley
3ad43b0823 (internal): make org-roam--org-link-file-bracket-re more intelligible (#749) 2020-06-03 12:38:56 +08:00
Jethro Kuan
b2594b84ae (docs): add section introducing the Zettelkasten method (#719) 2020-05-31 14:22:44 +08:00
Jethro Kuan
3440e647c0 (fix): add org-roam--directory-files-recursively (#737) 
Emacs 26 does not have the follow-symlinks option in
`directory-files-recursively`, so we have to add it ourselves.
 2020-05-30 22:32:30 +08:00
Jethro Kuan
1d28b07a7c (fix): org-roam--list-files: canonicalize filenames (#735) 2020-05-30 20:32:32 +08:00
Jethro Kuan
195669ad10 (docs): Add missing Org package-install instructions (#734) 2020-05-30 19:04:42 +08:00
ulfl
47feff5a8b (feat): allow for symlinks in the org roam directory (#733) 2020-05-30 18:52:25 +08:00
N V
7200364d31 (internal): remove org-roam--touch-file (#718) 
Unused function.
 2020-05-28 02:37:01 -04:00
Jethro Kuan
873a314746 (fix): hide citelinks if buffer has no ROAM_KEY (#717) 2020-05-28 14:23:18 +08:00
N V
91c905d7e3 (docs): org-roam.el clarify documentation (#716) 
Fix typo, reword docstring, remove decorative ellipses
 2020-05-28 14:12:01 +08:00
Jethro Kuan
f9a9f15a8b (fix): don't print no citelinks if org-ref is not present (#714) 
Change confusing behaviour where org-roam buffer prints "no citelinks"
even when org-ref is not present.
 2020-05-28 13:53:10 +08:00
N V
9ddadc9c25 (internal): org-roam-doctor require s, dash (#715) 
Silence flycheck warnings
 2020-05-28 01:44:13 -04:00
Troy Hinckley
d0fab34287 (fix): fix support for Emacs 26 built-in org (#711) 
org-make-link-string was changed to org-link-make-string in org 9.3. But Emacs
26 ships with org 9.1. Defining an alias to the old function name when using an
older org version.

Co-authored-by: N V <44036031+progfolio@users.noreply.github.com>
 2020-05-28 13:35:24 +08:00
N V
e3281fc31f (internal): Exclude org-roam-compat.el from linting (#713) 
org-roam-compat.el may contain symbols that belong to other packages.
e.g. functions backported to older versions of Org mode.
 2020-05-28 01:22:51 -04:00
N V
5ee38f2d89 (fix): autoloaded commands load org-roam-mode (#712) 
Users should not have to explicitly enable the minor mode before using
autoloaded commands.
 2020-05-28 00:25:19 -04:00
N V
2e220f511e (fix): org-roam-db-build-cache filter non-file input (#709) 
If a shell command is used to find files, it may include
output from another command.

see: #706, #688
 2020-05-27 15:15:55 +08:00
Jethro Kuan
1581d875ce (fix): doctor: add ROAM_KEY to supported props (#708) 2020-05-27 13:53:30 +08:00
Jethro Kuan
50cc81c76d (internal): use emacsql-sqlite3 everywhere (#701) 2020-05-27 13:20:06 +08:00
Jethro Kuan
f95cea7067 (feat): doctor: add check for misspelled roam properties (#703) 2020-05-26 14:52:51 +08:00
Jethro Kuan
41a1970c6f (internal): add BACKERS.md (#702) 2020-05-26 14:41:09 +08:00
Jethro Kuan
8818f50f41 (fix): fix symlinked directories and files not picked up (#700) 
The implementations for org-roam--list-files-{find,rg} did not follow
symlinks, which cause them to not pick up symlinked files and
directories.
 2020-05-26 13:46:08 +08:00
Jethro Kuan
ea6bd215fc (fix): set default org-roam-list-files-commands for windows to nil (#698) 2020-05-25 13:26:46 +08:00
N V
a05b1ebcc3 (internal): refactor org-roam-find-file logic (#691) 
Fail faster in case of nested capture.
Simplify logic for completions.
 2020-05-23 17:42:47 -04:00
N V
214f9df844 (fix): org-roam--list-files strip ANSI color codes (#689) 
Prevent shell commands from passing ANSI color codes through to callers.

see: #688
 2020-05-22 23:51:52 -04:00
N V
4f5a82e291 (internal): org-roam.el formatting (#687) 
Organize org-roam.el:
- Move functions so they are defined before they are referenced
- Move defcustoms to appropriate section, sort alphabetically
- Move interactive commands to appropriate section, autoload, sort.

Should not change any behavior, but make review easier.
 2020-05-22 21:34:50 -04:00
Mykhailo Shevchuk
4d0b5734c8 (fix): fix org-roam--list-files escape (#684) 2020-05-22 21:14:03 +08:00
Lau Siaw Young
4cd0fe4e41 (internal): add rg and find support for org-roam--list-files (#664) 
Speeds up org-roam--list-files using external tools. Simple benchmarks:

(benchmark 1000 '(org-roam--list-files-rg "./jethrokuan/braindump"))
"Elapsed time: 9.012230s (0.399595s in 5 GCs)"

(benchmark 1000 '(org-roam--list-files-find "./jethrokuan/braindump"))
"Elapsed time: 5.543965s (0.318566s in 4 GCs)"

(benchmark 1000 '(org-roam--list-files-elisp "./jethrokuan/braindump"))
"Elapsed time: 55.781495s (3.220956s in 41 GCs)"

Co-authored-by: N V <44036031+progfolio@users.noreply.github.com>
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-05-22 14:25:29 +08:00
N V
1eefc264f5 (fix): org-roam-graph--build notify user when build starts (#683) 
Displays a message to user to let them know the build (which may take
a variable amount of time) has started.
 2020-05-21 22:19:27 -04:00
N V
525a58dd86 (fix): org-roam-graph--build in seperate process (#679) 
org-roam-graph--build accepts a callback function which is passed the
resultant graph file as its sole argument. This prevents a race between
graph building and opening.

See: #666
 2020-05-21 13:03:16 -04:00
Jethro Kuan
4a9401dd40 (feat): org-roam-doctor: add ROAM_TAGS and ROAM_ALIAS checks (#680) 2020-05-21 21:08:52 +08:00
Jethro Kuan
dd2406ec92 (fix): fix 'ref context not returning path to file (#678) 2020-05-21 13:14:06 +08:00
Jethro Kuan
c4189ffa04 (internal): remove github stale bot (#676) 
bad bot.
 2020-05-20 13:42:37 +08:00
Chris Binz
e3d101f495 (doc): Update org-roam-bibtex repo URL (#675) 2020-05-19 15:12:28 -04:00
Sayan
2cced712fa (docs): add landing page (#673) 
Fixes #623 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-05-19 23:41:48 +08:00
Jethro Kuan
cce2db8b5a (release): v1.1.1 (#668) 2020-05-18 22:04:51 +08:00
Jethro Kuan
2147adf95c Create FUNDING.yml 2020-05-18 21:27:31 +08:00
Jethro Kuan
d2654f6023 (docs): add a nice default theme (#667) 2020-05-18 19:15:12 +08:00
N V
78b518efd3 (fix): org-roam-capture--capture shadow org-capture-templates-contexts (#662) 
Lexically bind org-capture-templates-contexts to nil before calling org-capture
with org-roam-capture-templates. Otherwise, contexts may shadow
org-roam-templates which have same keys as org-capture-templates.

mentioned in #651
 2020-05-17 11:51:25 -04:00
N V
1b5e55b6c4 (fix): org-roam-capture allow creating new file (#661) 
Set title correctly when no match found in prompt's candidates.
fixes #651
 2020-05-17 11:36:15 -04:00
Jethro Kuan
4b45f1dbf5 (fix): fix link updating on file-renames (#660) 
Fixes #647: file: links are now updated to reflect the directory change.
Also fixes #554: rename-files to directories are also resolved correctly now.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-05-17 18:51:52 +08:00
N V
e0aee184a7 (fix): prevent org-roam-version from loading org-roam-dev (#659) 
Instead of visiting file, insert library into temp buffer.
Prevents loading .dir-local dev environment, accompanying unsafe-variable prompt.
Prevents interference with org-roam.el if already open.
 2020-05-17 03:41:40 -04:00
N V
eae97487dc (internal): fix free variable reference (#658) 
Define org-roam-backlinks-mode before it is referenced.
 2020-05-17 02:56:15 -04:00
N V
f5a9dfab9b (fix): Require seq.el (#657) 
seq.el is is not guaranteed to be loaded otherwise.
 2020-05-17 02:20:48 -04:00
N V
7844827757 (feature): org-roam-diagnostics command (#653) 
Automates collection of user environment information.
 2020-05-17 01:57:38 -04:00
N V
74f12ee8aa (internal): org-roam-version save-excursion (#656) 
Restore user's point in org-roam.el
 2020-05-17 01:46:41 -04:00
N V
055669817a (feature): org-roam-version command (#655) 
Useful for diagnostic information.
Should be supplemented with finer grained info (commit hash would be
ideal) once we figure out a more sophisticated approach.
 2020-05-17 13:33:53 +08:00
N V
1fc08b4428 (internal): inline minor-mode keymaps (#654) 
define-minor-mode macro creates appropriate symbol/documentation for
inlined keymaps.
 2020-05-17 01:24:21 -04:00
N V
cfe3b19a73 (doc): bug_report.md request more info (#652) 
Request interactive commands for more build/version info.
Request Org mode version.
 2020-05-16 23:24:29 -04:00
Leo Vivier
1bc1559743 (fix): fix regression in find-ref (#650) 
Fixes #649.
 2020-05-17 00:09:58 +02:00
Leo Vivier
265182a698 (fix): adapt find-ref to new format (#646) 2020-05-16 14:03:37 +02:00
Jethro Kuan
4b4ebf76c7 (fix): fix parsing for ido (#645) 
This reverts commit 47763f49fd, after #643
reverted completions from hash-table to alist.
 2020-05-16 19:38:52 +08:00
Leo Vivier
3bc174a6f0 (fix): reimplement mtime sorting (#642) 2020-05-16 19:32:23 +08:00
Jethro Kuan
8091f4598e (internal): revert completions from hash table to alist (#643) 
Initially we thought that using hash-tables would shave some seconds
because searching for a key is O(1), but when we present completions, we
typically want them sorted, and hash-tables do not support sorted keys.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-05-16 18:17:37 +08:00
Leo Vivier
1267a43043 (fix): refactor get-ref-path-completions (#633) 
* (fix): refactor get-ref-path-completions

* Remove leftover variable

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-05-16 08:40:41 +02:00
N V
8ff09b4b6d (docs): Mention steps to provide backtrace in bug_report.md (#641) 2020-05-15 22:54:37 -04:00
Leo Vivier
2499c7e220 (feat): add COMPLETIONS argument to insert and find-file (#637) 
Needed for smoother interaction with ORB.  I’ve elected to keep FILTER-FN for
the moment, even though it’s a bit redundant, and the description in the
docstring is not correct with the addition of tags.
 2020-05-16 01:29:18 +02:00
Leo Vivier
d816250614 (fix): move from alist to hash for find-ref (#640) 2020-05-16 01:23:36 +02:00
p4v4n
47763f49fd (fix): fix parsing of new hash-table for ido 
* Use hash-table-keys to extract titles for ido

* Same change for helm
 2020-05-16 01:01:35 +02:00
Leo Vivier
9961a22a8c (fix): replace if with when (#632) 2020-05-15 20:23:06 +08:00
Jethro Kuan
f390593cfb (feat): Add a tagging system (#604) 
Tags are used as meta-data for files: they facilitate interactions with notes where titles are insufficient. For example, tags allow for categorization of notes: differentiating between bibliographical and structure notes during interactive commands.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
Co-authored-by: N V <44036031+progfolio@users.noreply.github.com>
 2020-05-15 16:10:11 +08:00
N V
59c18c0e8c (internal): org-roam-dev -> sentence-end-double-space nil (#629) 
Required by CI.
 2020-05-15 13:11:19 +08:00
Allard Hendriksen
3df3b6519c (doc): fix org-roam-buffer-no-delete-other-windows (#628) 
It appears the option has changed name, but this was not yet reflected
in the documentation.
 2020-05-14 22:52:27 +02:00
Jethro Kuan
b47b76aa41 (refactor): refactor title extraction (#625) 
Introduces '(org-roam-title-sources), which can be a list of lists. Each symbol corresponds to a function, that when called returns a list of titles. If the element is a list, use the first function in the list that returns a successful result.
 2020-05-14 19:45:07 +08:00
Günter Zöchbauer
abb36d11ef (docs): remove redundant word in docstring (#626) 2020-05-14 19:04:59 +08:00
Jethro Kuan
e55a38530d (fix): fix org-roam-doctor broken-link checker (#624) 
The checker originally returns reports of wrong format when there are no
errors
 2020-05-14 13:51:35 +08:00
Jethro Kuan
80bc19cbda (docs): update manual location (#622) 2020-05-13 20:19:31 +08:00
Jethro Kuan
85b3e488b2 (ci): fix 2020-05-13 19:56:06 +08:00
Jethro Kuan
5a9f765a49 (ci): move images to the correct location 2020-05-13 19:54:08 +08:00
Jethro Kuan
1c7c5b3b9b (ci): add nojekyll to docs 2020-05-13 19:48:39 +08:00
Jethro Kuan
4266a81b51 (ci): build the correct folder, clean builds 2020-05-13 19:43:36 +08:00
Jethro Kuan
36940e1eef Revert "(ci): deploy docs to docs branch" 
This reverts commit 176aac67e6.
 2020-05-13 19:39:12 +08:00
Jethro Kuan
176aac67e6 (ci): deploy docs to docs branch 2020-05-13 19:36:36 +08:00
Jethro Kuan
376ff71616 (ci): run doc build commands directly (#621) 2020-05-13 19:35:48 +08:00
Jethro Kuan
232921b9a1 (docs): track landing page (#620) 2020-05-13 19:26:37 +08:00
Jethro Kuan
9e2998c580 (ci): remove old docs, add landing page (#619) 2020-05-13 19:24:17 +08:00
Jethro Kuan
e44b84b791 (ci): make multi-page manual (#618) 2020-05-13 18:56:42 +08:00
Jethro Kuan
5e63bf32ed (ci): makeinfo -> texinfo (#617) 2020-05-13 18:49:18 +08:00
Jethro Kuan
e62bda799a (docs): use gh actions to deploy documentation (#616) 2020-05-13 18:45:32 +08:00
Jethro Kuan
46975107a2 (internal): remove assignment in issue templates (#615) 2020-05-13 17:58:34 +08:00
N V
b388fd3db2 (refactor): org-roam-db--clear pull tables from schemata (#611) 
Programatically pull tables from schemata, rather than manually
specifying each table.
 2020-05-13 02:24:50 -04:00
N V
e0cefa7377 (refactor): org-roam-db--clear-file pull tables from schemata (#613) 
Programatically pull tables from schemata, rather than manually
specifying.
 2020-05-13 14:14:46 +08:00
N V
fca1777648 (internal): Summarize features (#608) 
* (internal): Summarize features

Replace generic package description in features' first line summary.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-05-12 15:06:19 -04:00
N V
1722fae9af (internal): org-roam-dev use directory-local variable (#607) 
Add .dir-locals.el to load org-roam-dev for all source files.
 2020-05-12 13:46:12 -04:00
N V
3727f015cd (internal): add org-roam-dev.el (#606) 
Help ensure source code consistency.
emacsql indentation for now, but can easily be expanded as needed.
 2020-05-13 01:21:54 +08:00
Jethro Kuan
a85205e7bc (fix): Respect org-roam-file-extensions during file creation (#602) 2020-05-12 19:08:00 +08:00
Leo Vivier
b4927abbd7 (fix): Enforce default for ‘org-roam-index-file’ (#599) 2020-05-12 16:12:14 +08:00
N V
ad5fca5440 "Refactor org-roam-message as a function" (#595) 
* Refactor org-roam-message as a function

Add to commentary that org-roam-macs may contain other utility
functions (similar to org-macs).

* Fix typos

* Try again

* Fix typo

* fix syntax error

* fix syntax error

* Apply args correctly

* Refactor with funcall

* Revert "Refactor with funcall"

This reverts commit 0807252d64.

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-05-10 23:17:55 +02:00
Jethro Kuan
3efe315ff1 (internal): add org-roam-message (#593) 
This macro simplifies message printing, so we can respect
`org-roam-verbose` in more places. Also silences more messages when
`org-roam-verbose` set to false.
 2020-05-10 16:44:28 +08:00
Jethro Kuan
d68d1f8ebb (feat): add org-roam-doctor (#570) 
`org-roam-doctor` provides a diagnostic tool for checking an Org-roam
file for things that are broken. Currently implemented is a check for
broken links, and methods to fix them. The checker is designed to be
extensible.
 2020-05-10 13:57:18 +08:00
Leo Vivier
c70f2d5f54 (fix): update repo root to group (#591) 2020-05-10 13:48:16 +08:00
Günter Zöchbauer
d3206b797a (docs): link to discourse in README (#577) 
Also, add information about Graphviz on the README.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-05-09 19:54:05 +08:00
Leo Vivier
dee540b62f (fix): do not store empty-string refs in db (#586) 
* (fix): do not store empty-string refs in db

* Error when ROAM_KEY is empty

* Handle nil

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-05-09 13:47:56 +02:00
Leo Vivier
46fd2a9a68 (fix): allow group templates in capture-templates (#584) 
Co-authored-by: N V <44036031+progfolio@users.noreply.github.com>
 2020-05-09 18:08:08 +08:00
Leo Vivier
c1bfa99ace (fix): make graph--build error on non-string (#580) 
* (fix): make graph--build error on non-string

* Replace let* with let

* Fix wording
 2020-05-07 20:38:17 +02:00
Leo Vivier
9bc80ff9f7 (fix): improve error message on missing executable (#579) 2020-05-08 01:44:28 +08:00
Jethro Kuan
1912beebc3 (docs): mention where to modify org-roam templates (#575) 
Addresses #573
 2020-05-07 16:33:42 +08:00
Jethro Kuan
f8f7e6009c (internal): add longer sleep time to tests (#574) 2020-05-07 15:41:58 +08:00
Leo Vivier
689f559080 (doc): Add a gif for ORB (#571) 2020-05-06 18:59:09 +08:00
Leo Vivier
3ca2d9f4ca (doc): Improve wording 'A Preview' (#568) 
* (doc): Improve wording of the first paragraph

Can’t believe nobody told us that we used ‘screenshot’ instead of
‘screencast’. :(

* Fill to 72
 2020-05-05 14:19:00 +08:00
Leo Vivier
cd0850f1c1 (feat): simplify format of INFO for find-ref and add FILTER (#567) 
* (feat): simplify format of `INFO` for find-ref

The format of the `INFO` argument of `org-roam-find` has been simplified, thanks
to the split of `type` and `ref` in the db permitted by #547.

The non-interactive behaviour of `org-roam-find-ref` has also been isolated
into `org-roam--find-ref`.  Even if it makes us repeat ourselves a bit, it
avoids having to nil the interactive argument just to get the non-interactive
us, which I think is better syntax.

* (feat): implement get-ref-path-completions filtering
 2020-05-04 22:31:28 +02:00
Leo Vivier
11e15594cc (feat): add custom face for invalid links (#564) 
* (feat): add custom face for links without destinations

* Rename to ‘invalid’

* Update docstring

* Remove ‘typically’
 2020-05-04 15:47:27 +02:00
Jethro Kuan
f6e84caf72 (chore): inherit org-roam-link-current from org-link (#563) 
A better default for org-roam-link-current is the original org-link
face, rather than org-block.
 2020-05-04 20:58:12 +08:00
Göktuğ Karakaşlı
11d239d661 (feat): fix citation links not showing up in graph (#547) 
This change adds a `type` column to the refs column, and strips the prefix before storing the key in the `refs` table.
 2020-05-04 20:44:15 +08:00
Jethro Kuan
7df50c14ec (internal): make lint errors fail CI, and disable spellcheck during linting (#561) 
- make lint errors fail CI
- disable indentation linting
- disable package linting for org-roam-macs.el
- disable spellcheck for checkdoc
- fixes compilation errors
 2020-05-04 15:17:39 +08:00
Jethro Kuan
a723199d68 (feat): apply error face if file link is broken (#560) 2020-05-04 12:57:43 +08:00
N V
1bbfb0cdc9 (ehancement): Improve org-roam-graph (#559) 
Allow showing/building the whole graph from any buffer.
Allow programatically specifying connected component path.
 2020-05-03 18:03:02 -04:00
Jethro Kuan
69d4f05a13 (feat): add prefix argument to force database rebuild (#553) 
* (feat): add prefix argument to force database rebuild

* Update changelog
 2020-05-03 18:40:32 +08:00
Jethro Kuan
4cad2cf6e6 (internal): use Make and Org to build manual (#546) 2020-05-03 18:06:27 +08:00
Tim Quelch
e698ed7f53 Generate cite backlinks using all org ref cite types (#551) 
This would fail on pathological cases where the key itself contains other prefixes e.g. if the key
is `cite:parencite:autocite:key`. Although this is unlikely...

To use org-ref-cite-types, we must ensure that org-ref is loaded. This would likely already be done
otherwise as the user is obviously using cite links.
 2020-05-02 18:50:11 +08:00
Jethro Kuan
0132546e56 Create stale.yml 2020-05-01 20:16:57 +08:00
Mykhailo Shevchuk
a8e2544435 graph: add an option of wrapping the title (#542) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-05-01 19:49:46 +08:00
Tim Quelch
1ad3539c54 (fix): ensure that multicite links are correctly split (#545) 
* Ensure that multicite links are correctly split

org-ref multi-citations are handled by "cite:key1,key2". In the org-roam databases this was
previously stored as a single "cite" link to the (non-existing) key "key1,key2". This means that
cite backlinks and cite graph behaviour does not work correctly for these links.

This fix will split any cite links with a comma into separate links to each individual ref

* Refactor with ->>

* Refactor to use org-ref-split-and-strip-string instead

* Update changelog with #545

* (fix): optimize processing

* (fix): avoid repetition

Co-authored-by: Leo Vivier <leo.vivier+dev@gmail.com>
 2020-05-01 11:57:28 +02:00
Leo Vivier
5b773b687b (doc): add key-binding for index in default configs (#543) 
* (doc): add key-binding for index in default configs

* (fix): rename org-roam-find-index to -jump-to-index
 2020-05-01 09:07:37 +02:00
Leo Vivier
08aa5c630d (feat): reintroduce org-roam-link-current face (#516) 2020-04-30 20:20:33 +08:00
Leo Vivier
e05ee1240d (feat) cond display relative subdir in title for selection (#427) 
* (feat) cond display relative subdir in title for selection

A title can now be constructed as ‘subdir/file-title’ where ‘subdir’ is the
sub-directory relative from ‘org-roam-directory’.

When ‘org-roam-title-include-subdirs’ is non-nil, ‘org-roam--extract-titles’
now outputs titles in this format.

* (fix) improve docstrings

* (feat) add var for modifying subdir-separator

* (fix) nitpick docstring

* (doc) document subdir creation in templates with :file-name

* (feat) make subdir-format accept a function

* (fix) respect docstring one-line-description

* (fix) address checkdoc errors

* (fix) also add subdirs when db--update-titles

* (feat) improve modularisation

`org-roam--extract-titles' is now reverted to its default definition, i.e. it
doesn’t format the titles.  In its stead,
`org-roam--extract-and-format-titles' is created to both extract the titles
and process all of them with `org-roam--format-title', which is a much better
way to do this.

* Refactor with ->>

* Refactor with let*

Pretty sure I got confused because I thought I needed to use the result of the
db-queryr.

* Remove useless ->>
 2020-04-30 13:13:19 +02:00
Jethro Kuan
65d99e998c (feat): prettier graph defaults (#541) 
Use settings provided by @tecosaur. Closes #539.
 2020-04-30 13:56:54 +08:00
Leo Vivier
ea3f5d00a0 (feat) expand rel-links upon extraction (#520) 2020-04-30 13:44:45 +08:00
Jethro Kuan
7680663205 (feat): optionally use headline as title (#538) 
Optionally pulls title from the first headline in Org file. Closes #506.
 2020-04-29 12:42:55 +08:00
Leo Vivier
d0819aeffb (feat) implement org-roam-find-index (#513) 2020-04-29 12:08:42 +08:00
Jethro Kuan
bd4b9d41e8 (bugfix): quote graphviz configuration options (#537) 
Always quote graphviz configuration options. This allows passing
configurations with spaces. Fixes #535.
 2020-04-29 11:30:39 +08:00
Leo Vivier
4142300501 (internal): refactor org-roam--pluralize (#525) 2020-04-26 19:07:19 +08:00
Jethro Kuan
487025aa2f (chore): remove org-roam-completion-fuzzy-match (#523) 
Remove the fuzzy matching variable introduced in #289. The rationale is
addressed in
https://github.com/jethrokuan/org-roam/issues/514#issuecomment-619438401:
Helm, Ido and Ivy have their own mechanisms for fuzzy search, and can be
tweaked using their own configuration options outside of org-roam, e.g.
through `ivy-re-builders-alist`.
 2020-04-26 18:32:27 +08:00
Leo Vivier
bd3c97bb30 (feat) conditionally pluralize heading in org-roam-buffer (#521) 2020-04-26 17:51:32 +08:00
Jethro Kuan
265a3054be (fix): resolve symlinks during cache build (#524) 
Fixes #518.
 2020-04-26 17:42:57 +08:00
Michael Glaesemann
8bb2465e61 (docs): update reference to Roam Protocol documentation (#519) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-26 17:29:21 +08:00
Rafael Accácio Nogueira
c3a5544da9 (docs): add docs for qutebrowser keybindings (#512) 2020-04-26 17:23:11 +08:00
Jürgen Hötzel
963692f353 (bugfix): Fix invalid usage of error handler (#511) 
The error handler was never invoked when executing `org-roam-graph-viewer` failed
 2020-04-25 18:53:09 +08:00
Jethro Kuan
d01f7b2daf (bugfix): fix inserting backup files into database (#509) 
In #470, the `and` clause was removed, so `org-roam--org-roam-file-p`
returns `t` on `foo.org~` backup files. This PR adds that back in.

In addition, the `after-save-hook` function was not checking for whether
the file was within the org-roam system, which meant files from outside
`org-roam` would also be added into the database. This PR adds a guard
clause.
 2020-04-22 14:35:47 +08:00
Leo Vivier
8a99febd0b (fix): lowercase username in url to org-roam-bibtex (#505) 2020-04-22 14:28:30 +08:00
Josh English
b5786edb30 (docs): Fix org-roam-protocol JS Bookmarklet (#508) 2020-04-22 13:57:12 +08:00
Jethro Kuan
dce8c47d6e (docs): mention org-roam-bibtex (#503) 2020-04-21 20:55:12 +08:00
Jethro Kuan
27a63b59b1 (release): 1.1.0: update version headers in source (#502) 2020-04-21 20:50:24 +08:00
Jethro Kuan
339336a27f (release): 1.1.0 (#501) 2020-04-21 20:43:21 +08:00
Jürgen Hötzel
a35454bb7e (internal): Simplify org-roam--list-files implementation. (#497) 
Use destructive elisp functions to optimize for speed and memory
usage.

Refs #104
 2020-04-20 18:28:33 +08:00
N V
228af5b6be (fix): Remove old definition of org-roam-graph--open (#498) 
Fixes #496
 2020-04-20 02:24:18 +08:00
Leo Vivier
89b941a207 (feat) implement after-find-file-hook for org-roam-capture (#482) 
Allows user to run functions when an `org-roam-capture` is successful.  This
might come in handy for moving point after finding the new file, since right
now, it is at `(point-min)`.
 2020-04-19 22:45:09 +08:00
N V
258d6f8a52 (feat): Allow function for org-roam-graph-viewer (#488) 
User may specify a function to open the org-roam graph.
Adds more error handling to org-roam-graph--open.

See #440
 2020-04-19 19:00:33 +08:00
N V
dc65e58405 (refactor): org-roam-graph (#490) 
- Consolidate graph build/display commands into org-roam-graph command
  See #450
- Require org-roam-db
  Rather than declaring its functions.
- Move obsolete variable org-roam-graph-node-shape to org-roam-compat
- org-roam-graph--build-connected-component accepts a file argument
  Allows building a graph without having the target file as the current
  buffer
- Eliminate repeating code
- Fix checkdoc warnings
 2020-04-19 15:04:24 +08:00
Jürgen Hötzel
de4f5477d8 (feat): Use TITLE as description when linking before first heading (#491) 
Fixes #487
 2020-04-19 00:41:38 +08:00
Leo Vivier
9e138e259a (feat) remove user-error for org-roam-insert (#486) 
* (feat) remove user-error for org-roam-insert

Closes #477.

* (fix) use absolute path when buffer has no associated file

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-18 13:10:14 +08:00
Leo Vivier
ba80a31fe0 (feat): add optional FILTER-FN argument for org-roam-find-file and org-roam-insert (#481) 2020-04-18 04:54:17 +08:00
Michael Glaesemann
6175739b33 (docs) Provide examples of using template expansion and function overrides. (#478) 2020-04-17 18:31:39 +08:00
Leo Vivier
35b20de45f (fix): ensure that directory exists before capturing to dir (#476) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-17 12:39:03 +08:00
Sayan
06afa27725 (docs): export: add snippet for backlinks with contents. (#466) 2020-04-17 12:34:40 +08:00
Jethro Kuan
e1873a6a16 (internal): extract daily notes functionality (#473) 
Beyond just an extraction, this is also a simplification. It removes two
variables: `org-roam-date-filename-format` and
`org-roam-date-title-format`, in favour of directly specifying them in
the `org-roam-dailies-capture-templates`.

`org-roam--file-for-time` is also vastly simplified to use org-capture's
default time expansion utilities, by setting the capture template's
`:default-time` appropriately.
 2020-04-17 03:25:16 +08:00
Jürgen Hötzel
e33c144298 (bugfix): add workaround for undocumented file-truename behavior (#470) 
This prevents and error being generated when the agenda is displayed.

Fixes #408
 2020-04-16 02:53:43 +08:00
Jethro Kuan
ea1ba21825 (chore): inline links in changelog (#467) 
I had initially thought that keeping them separate would be cleaner, but
it's very easy to forget to add the links at the bottom of the
changelog. Relevant emacs-lisp that did this:

(replace-regexp "\\[gh-\\([0-9]+\\)\\]" "(https://github.com/jethrokuan/org-roam/pull/\\1)")
 2020-04-15 15:28:47 +08:00
Jethro Kuan
d7fc91e047 (feat): Add support for different file extensions (#465) 
Adds `org-roam-file-extensions`, which allows org-roam to detect file extensions other than .org. Fixes #461
 2020-04-15 15:02:05 +08:00
Michael Herold
a4a2ac8d19 Use MELPA for installing in Spacemacs (#462) 
Now that org-roam is out on MELPA, let's suggest that people use it
instead of GitHub to install the package.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-15 14:34:23 +08:00
Sayan
f79ee9e850 Correct database query function (#463) 
`org-roam-sql` is obsolete now. Also changed the syntax that works for the new `org-roam-db-query` function.
 2020-04-15 14:09:58 +08:00
Jethro Kuan
a71176ee40 (docs): mention company-org-roam in documentation (#457) 2020-04-14 17:00:13 +08:00
Jethro Kuan
6bdde3a634 (bugfix): fix org-roam-graph--open (#456) 2020-04-14 16:31:14 +08:00
Noboru
b33300a23d (docs): fix broken format in win-install doc (#438) (#451) 2020-04-14 13:17:05 +08:00
N V
8c7bc09f9b (fix): Use make-temp-file in org-roam-graph-build (#454) 
Create a new temporary file for each graph that is built.

See: #453
 2020-04-14 13:14:23 +08:00
Roland Coeurjoly
0a9ca736e4 (docs): fix small typo (#445) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-13 14:55:12 +08:00
N V
3506f16648 (fix): org-roam.el eval-when-compile subr-x (#449) 2020-04-13 12:12:30 +08:00
Jürgen Hötzel
772505ba70 (bugfix): Explicitly load subr-x library (#429) 
Ensure the `if-let*` macro definitions is available during compile-time
 2020-04-12 17:18:09 +08:00
Noboru
6392a8b5df (docs): fix broken format+typo in win-install (#438) (#444) 
Co-authored-by: nobiot <me@nobiot.com>
 2020-04-12 17:05:27 +08:00
Tim Quelch
580a320c66 (feat): graph: add cite links to graph (#439) 2020-04-12 14:38:58 +08:00
Noboru
0e79bbb75a (doc) add Windows installation instruction (#397) (#438) 
Co-authored-by: nobiot <me@nobiot.com>
 2020-04-12 11:35:42 +08:00
Johann Klähn
4af4d2e4d5 (feat): split building and showing of the graph into two functions (#426) 2020-04-11 16:41:49 +08:00
N V
18939fcccd (doc): ref-capture-templates > capture-ref-templates (#433) 
See: #430
 2020-04-11 16:38:46 +08:00
Alexey Shmalko
1b13c426aa (feat): add org-roam-graph-edge-extra-config (#435) 
Introduces `org-roam-graph-edge-extra-config` to add options to edges
 2020-04-11 13:41:21 +08:00
N V
bee8e506c2 (refactor): Move obsolete vars/functions to org-roam-compat (#434) 2020-04-11 13:25:12 +08:00
Leo Vivier
c280f249a9 (fix) typo in doc, titles -> refs (#436) 2020-04-11 12:36:59 +08:00
Johann Klähn
ba1782d361 (feat): graph of bfs from given node (#418) 2020-04-11 04:20:43 +08:00
Leo Vivier
e327fb3f0c (fix): reuse variable defined in let-form (#431) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-11 04:13:16 +08:00
N V
40dc3a5af8 (refactor): org-roam-db.el eval-when-compile subr-x (#432) 
Prevents unnecessary evaluation when compiled .elc is loaded.
From the commentary of subr-x.el:
;; NB If you want to use this library, it's almost always correct to use:
;; (eval-when-compile (require 'subr-x))

See: #429
 2020-04-11 03:55:24 +08:00
Leo Vivier
05c9e8e2e7 (feat): add org-roam-find-directory (#424) 2020-04-10 20:11:39 +08:00
Jürgen Hötzel
df20754fb0 (bugfix): Explicitly load subr-x library (#425) 
Ensure the `when-let` macro definitions is available during
compile-time.
 2020-04-10 19:19:00 +08:00
James Ravn
dddbe286de (feat): add customization to set no-delete-other-windows (#422) 
Adds `org-roam-buffer-no-delete-other-windows`, which controls the behaviour of the org-roam buffer side window upon `delete-other-windows`.
 2020-04-10 17:50:52 +08:00
Jürgen Hötzel
92500b1338 (bugfix): Use predicate to check for a org-roam-capture process (#413) 
Instead of using a global variable to check for a existing capture,
leverage the :org-roam plist property of the buffer-local variable
`org-roam-capture-current-plist`.

This prevents a lockout if the capture buffer is killed
 2020-04-10 17:03:49 +08:00
N V
772504c488 (internal): modularize org-roam-buffer (#406) 
Split functionality related to the org-roam-buffer into its own
feature/file.

Introduce `org-roam-buffer-prepare-hook' to allow customizations of the
org-roam-buffer content.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-10 14:38:41 +08:00
Jethro Kuan
6e97003967 (fix): Detect all org-ref cite types (#417) 2020-04-09 12:26:40 +08:00
N V
dd3fd592bb (internal): Move aliases to org-roam-compat.el (#412) 
Same strategy Org uses. Consolidates backward compatibility into a
single location. Leverages `define-obsolete-*-alias' macros.
 2020-04-09 12:16:22 +08:00
Johann Klähn
67495e269a (feat): allow creation of connected-component graph (#398) 2020-04-08 10:52:40 +08:00
Langston Barrett
72faa591fb (docs): fix typo eduring -> during (#405) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-07 15:30:07 +08:00
N V
c7a44b9f12 Move org-roam-capture command to org-roam-capture.el (#407) 2020-04-07 13:53:22 +08:00
Jethro Kuan
5120f8eac3 (chore): update Slack invite link (#403) 2020-04-06 18:23:51 +08:00
Jethro Kuan
e73bc78274 (feat): Add org-ref citation support (#374) 
Adds support for org-ref cite: links to the backlinks buffer.

Requires a db-rebuild, since the db schema has changed.
 2020-04-06 16:48:17 +08:00
N V
4ca2606a28 (docs): org-roam-db-build-cache (#396) 
Remove references to obsolete variable.
org-roam-build-cache -> org-roam-db-build-cache
 2020-04-04 03:50:10 +08:00
Langston Barrett
f9a4f3b7f7 (docs:) spacemacs: replace show-graph with graph-show (#393) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-04-02 13:40:53 +08:00
Jürgen Hötzel
8f28bd4ccf (feature): Add numeric prefix argument to org-roam-tomorrow (#392) 
Also add prefix argument to `org-roam-yesterday`.

This makes it possible to jump back or forward several days.
 2020-04-02 13:32:22 +08:00
N V
dfb8449680 Refactor org-roam--setup-buffer (#388) 
Change function name org-roam--setup-buffer org-roam--set-up-buffer.
Warn user and default to 'right when org-roam-buffer-position is
an invalid position.

Make better use of pcase to avoid repeating code.
 2020-04-01 13:16:09 +08:00
Jethro Kuan
48ccb084f0 (feat): Cache template variable entry (#387) 
Addresses
https://github.com/jethrokuan/org-roam/issues/285#issuecomment-606724827
 2020-04-01 12:09:41 +08:00
Jethro Kuan
f27e5f2384 (fix): Undo font locking changes in backlinks buffer (#386) 2020-04-01 11:50:16 +08:00
Jethro Kuan
e4f77eb586 (feat): Add org-roam-graph-node-extra-config (#385) 
org-roam-graph-node-extra-config is an alist containing additional node
configuration options, as per
https://graphviz.gitlab.io/_pages/doc/info/attrs.html

This also deprecates org-roam-graph-node-shape, which is a special case
of the node options
 2020-04-01 11:36:24 +08:00
philip-bl
2e3119e027 Allow top and bottom placement of the sidebar in addition to left and right (#380) 
* Allow placement of the sidebar on top or on bottom

* Add "let_sidebar_be_on_top_or_bottom" to the changelog

* Remove an unnecessary progn and replace an if with a pcase

As requested by jethrokuan in https://github.com/jethrokuan/org-roam/pull/380
comments.
 2020-03-31 18:34:23 +08:00
N V
b06e296e88 (chore): update org-roam-graph variable names (#383) 
See: https://github.com/jethrokuan/org-roam/issues/382
 2020-03-31 16:56:15 +08:00
bdarcus
04acbda916 (docs): simplifying doom installation instructions (#381) 
With the new `+roam` flag now added to doom emacs, this simplifies the instructions.
 2020-03-31 05:46:46 +08:00
Jethro Kuan
b86d2c8637 (docs): Add Org-roam video (#376) 2020-03-30 02:39:17 +08:00
Jethro Kuan
7dd371c023 (fix?): use helm-make-source instead (#375) 
Byte-compiled code should not contain macros.
 2020-03-29 21:30:23 +08:00
Jethro Kuan
58c07f74bc (docs): Add note about completion mechanism (#373) 2020-03-29 17:58:49 +08:00
Jethro Kuan
bc28c85dfc (hotfix): move capture in-process setting as late as possible (#372) 
This is a hotfix for #369. Currently, calling `org-roam-capture` sets
`org-roam-capture--in-process` to `t`, but cancelling the capture
process does not reset it to `nil`, causing false errors. The whole
nested org-capture processes workaround is brittle, this change moves it
as far back as possible, but the whole thing needs to be redesigned.
 2020-03-29 17:52:22 +08:00
Jethro Kuan
b607e56c5f (feat): Add interactive org-roam-capture (#371) 2020-03-29 17:29:57 +08:00
Jethro Kuan
ba835ef624 (fix): Add alias for 'org-roam--capture-get-point (#370) 
This ensures custom templates don't break
 2020-03-29 17:12:33 +08:00
Jethro Kuan
649af54640 (internal): remove company-org-roam (#368) 
company-org-roam is maintained separately, at jethrokuan/company-org-roam.
 2020-03-29 14:14:13 +08:00
N V
22b9d4bd22 (internal): modularize features (#363) 
Addresses #357
 2020-03-28 21:16:28 +08:00
Jethro Kuan
df29da1b6d (feat): add variable for muting messages (#359) 
Adds `org-roam-verbose`, which echoes messages that are not errors.
 2020-03-27 15:09:52 +08:00
Johann Klähn
de36d15d0f Turn org-roam-backlinks-mode into a minor mode (#355) 
This change makes `org-roam-open-at-point` non-interactive and adds it to
`org-open-at-point-functions`.  As a consequence, `org-open-at-point` will try
to visit an Org-roam link or preview text, before falling back to the default
behavior of Org mode.

Fixes #312.
 2020-03-27 13:06:44 +08:00
Jethro Kuan
3e0a49de03 (bugfix): change declare-function for helm-build-sync-source (#354) 2020-03-26 20:17:06 +08:00
Jethro Kuan
3add2c5a8b (feature): add org-roam-db-location (#350) 
`org-roam-db-location` sets the location of the Org-roam sqlite database.
 2020-03-24 12:22:00 +08:00
Jethro Kuan
4b6f580375 (bugfix): fix org-roam date functions filename format (#349) 
Previously the filename was not used in the capture template.
 2020-03-24 11:47:40 +08:00
Daniel Nicolai
23a8b0d722 Add warning: binding conflict with ranger layer (#348) 
This happened to me. The error message and backtrace information were not very clear
 2020-03-24 11:16:53 +08:00
Jethro Kuan
1433dbc316 (release): v1.0.0 (#341) 2020-03-23 15:34:21 +08:00
Jethro Kuan
def3d27d25 (internal): small refactor (#340) 2020-03-22 12:12:40 +08:00
Jethro Kuan
6fae1d8100 (chore): update internal Github settings (#339) 
Removes sponsor button, and disables 26.3 in testing matrix
 2020-03-22 11:37:23 +08:00
Jethro Kuan
07672213b6 (chore): fix bytecompile errors and checkdoc errors (#338) 2020-03-22 03:16:38 +08:00
Johann Klähn
5406827451 (internal): use org-link-make-string (#337) 
This takes care of properly escaping backslashes in file names.
 2020-03-22 02:46:36 +08:00
Jethro Kuan
214a8f771f (internal): reduce org-roam capture template key pollution (#336) 
Following #332, nest all org-roam related customization in to a single
key.
 2020-03-22 00:13:19 +08:00
Jethro Kuan
57f5e73192 (internal): force a reconnect on org-roam-build-cache (#335) 
This is to guard against scenarios where a db connection is still live, although it
may already be invalid (like in #331)
 2020-03-21 22:30:30 +08:00
Mykhailo Shevchuk
1352809451 ensure "%?" is present in the template string (#330) 
* ensure "%?" is present in the template string

- addresses #298
- fixes `org-capture-place-plain-text` throwing 'invalid search bound'
  when both :unnarowed t and "%?" is missing from the template string

* ensure "%?" is present in the template string

- if "%?" is missing, add it at the end of the template
 2020-03-21 20:56:20 +08:00
N V
8b37135aa2 (internal): refactor to remove hooks in a loop (#334) 
Removing hooks in a loop should be easier to extend/maintain.
More "DRY" than repeating calls to `remove-hook'.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-03-21 12:43:11 +08:00
N V
159e11c842 (internal): update cl.el functions to cl-lib versions (#333) 
cl is a deprecated library. cl-lib replaces it.
 2020-03-21 12:40:13 +08:00
Jethro Kuan
63b2eaaf86 (bugfix): throw an error on nested org-roam capture processes (#329) 2020-03-20 20:17:56 +08:00
Jethro Kuan
919d08732c (bugfix): fix nested org-roam-inserts not working (#328) 2020-03-20 00:57:32 +08:00
Thomas Proisl
97dfc4b980 (bugfix): fix `org-roam--completing-read' for ido (#324) 
For `ido-completing-read', `choices' must be a list of strings
 2020-03-19 16:23:04 +08:00
Jethro Kuan
4556f727ff (bugfix): fix org-roam-capture not saving file, and org-roam date functions (#321) 
* (bugfix): fix org-roam-captures not saving file

* (bugfix): fix org-roam date functions
 2020-03-18 01:11:08 +08:00
Jethro Kuan
6775f15ad1 (bugfix): prevent file open if capture is cancelled (#316) 2020-03-17 17:20:55 +08:00
Jethro Kuan
8f8ccf6797 (feat): clean-ups for org-roam-capture system (#315) 
This introduces 2 user-facing changes:

1. If a capture process is aborted, the file is not created if it
doesn't yet exist

2. If a capture process is aborted, org-roam-insert will not insert a
link
 2020-03-17 17:06:49 +08:00
Jethro Kuan
81dd880357 (bugfix): fix ugly node labels in org-roam graph (#314) 2020-03-17 13:00:45 +08:00
Jethro Kuan
c14ac7b613 (bugfix): fix Helm completing-read containing extra spaces on non-match (#309) 2020-03-16 17:42:57 +08:00
Jethro Kuan
08667d9c7d (bugfix): Fix Helm integration for completing-read (#306) 
Fixes #304, using PR #305 as the base, thanks @khinsen
 2020-03-16 13:00:12 +08:00
wannli
f544bd9ca1 hexify file url for org-protocol link (#299) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-03-15 21:55:54 +08:00
Jethro Kuan
66aff57cdb (bugfix): capture: prepend header template only on new file (#302) 2020-03-15 21:50:25 +08:00
wannli
f238e3fe02 (feat): order backlinks by filename (#300) 
Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-03-15 15:26:24 +08:00
Mykhailo Shevchuk
98fc273a0f (internal): less abusive use of org-capture (#294) 
`org-roam--capture-new-file` does not write anything to a file, all the templating is delegated to vanilla `org-capture`
 2020-03-15 13:41:36 +08:00
Jethro Kuan
a4df95b518 Create FUNDING.yml 2020-03-14 17:52:51 +08:00
Jethro Kuan
6f1154c90e (bugfix): remove nonexistent/redundant code (#297) 2020-03-14 14:55:53 +08:00
Jethro Kuan
486ba9c5a8 (feat): upgrade org-roam-graph-exclude-matcher to accept a list (#296) 
Closes #295
 2020-03-14 01:17:32 +08:00
Jethro Kuan
d28a83c992 (bugfix): fix unintuitive behaviour of capture insertion (#293) 
Ref #285
 2020-03-13 18:13:04 +08:00
Jethro Kuan
62ed117eb6 (feat): Support multiple org-roam-directories for company backend (#292) 
Fixes #276
 2020-03-13 14:03:53 +08:00
Jethro Kuan
a44b847596 (docs): add documentation for using neato (#291) 
Some prefer using neato for generating a graph (ref #263). This
documents how to do so.
 2020-03-13 13:37:55 +08:00
Jethro Kuan
e64890c80e (feat): add org-roam-date-title-format and org-roam-date-filename-format (#290) 
This PR supercedes #280. It allows users who use the date
functionality in Org-roam to customize the filename and title formats
of the created files.
 2020-03-13 13:29:49 +08:00
Jethro Kuan
4eaf69465e (feat): add 'ido and 'ivy support for completing-read (#289) 
Also adds org-roam-fuzzy-match, which for ivy and helm controls
whether completion candidates are fuzzy matched.
 2020-03-13 13:11:22 +08:00
Konrad Hinsen
0950ae3cc6 (feature): add support for Helm's completion system (#284) 
adds org-roam-completion-system, supporting helm as the default completion option.
 2020-03-12 19:34:27 +08:00
Jethro Kuan
0cab668d9e (bugfix): propagate org-roam-directory to temp buffers (#275) 2020-03-11 15:41:18 +08:00
Jethro Kuan
6095d01ef4 (feat): add a company-mode for link completion (#257) 
Adds company-org-roam, a company backend which autocompletes text into org file links
 2020-03-11 14:32:58 +08:00
海东
bd425e4427 (docs):fix typo in platypus installation (#274) 2020-03-11 11:37:01 +08:00
Jethro Kuan
65ead3c9ed (chore): fix more checkdoc errors (#270) 2020-03-11 00:55:42 +08:00
Jethro Kuan
be1d1f1d7b (feat): add org-roam-graphviz-extra-options (#269) 2020-03-11 00:44:07 +08:00
Jethro Kuan
f5d5b83b49 (bugfix): fix missed org-roam-link-title-format uses (#268) 
In #261 we allowed org-roam-link-title-format to be a function, but missed some of its uses during the update. h.t. @alanz
 2020-03-11 00:34:08 +08:00
Thomas Proisl
8a3945945b (bugfix): emove duplicate line from `org-roam--db-clear' (#267) 2020-03-10 15:35:34 +08:00
Jethro Kuan
7f09c76baf (fix): allow org-roam-insert in Org-roam file indirect buffers (#266) 2020-03-10 10:57:49 +08:00
Jethro Kuan
f6e75f995a (chore): cleanup buffer-file-name calls (#265) 
buffer-file-name uses the current-buffer if the argument is not passed
 2020-03-10 10:41:43 +08:00
Jethro Kuan
6ba9ffe9c8 (fix): Error if org-roam-insert is not called from Org-roam file (#264) 2020-03-10 10:36:36 +08:00
Jethro Kuan
5e0b7440a3 (feat): Allow function for org-roam-link-title-format (#261) 
Addresses #255
 2020-03-09 22:18:04 +08:00
Jethro Kuan
d16d001b9e (feat): add optional initial-prompt to org-roam-find-file (#259) 2020-03-09 16:43:48 +08:00
Jethro Kuan
f67e0b025a (docs): fix typo in vanilla installation (#254) 2020-03-08 20:49:17 +08:00
Jürgen Hötzel
b836f9fc35 (bugfix): Don't query about SQL proccess on Emacs exit (#253) 
Graceful shutdown is already guaranteed via `kill-emacs-hook`.

Refs #200

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-03-08 19:57:48 +08:00
Jethro Kuan
e138056115 (docs): fix documentation for manual installation (#252) 2020-03-08 17:43:07 +08:00
Jethro Kuan
63e0558d96 (chore): Cleanups for MELPA release (#251) 
* (chore): require minimum Org version 9.3

* fix bytecompile errors for org-roam.el

* fix checkdoc errors

* fix more things
 2020-03-08 15:58:13 +08:00
Jethro Kuan
3fccaef967 (chore): change main branch to master (#250) 2020-03-08 15:05:57 +08:00
Alexey Shmalko
6eb7238daf (feature): add org-roam-backlink face (#247) 2020-03-08 14:54:56 +08:00
Alexey Shmalko
fc79901682 (chore): drop org-roam-filename-noconfirm (#248) 
With org-capture integration, it does not seem to be used anymore.
 2020-03-08 11:15:41 +08:00
Jethro Kuan
46afa483a9 (docs): add documentation for exporting backlinks in Org file (#244) 
h.t. @jdiez17
 2020-03-07 23:49:43 +08:00
Jethro Kuan
f63f29ac05 (docs): Add link to slack invite (#242) 2020-03-07 15:05:16 +08:00
Jethro Kuan
e357693297 (release): v1.1.0-rc1 (#238) 2020-03-06 20:39:28 +08:00
Jethro Kuan
b7afb02015 (chore): Cleanup for MELPA release (#236) 2020-03-06 20:15:33 +08:00
Jethro Kuan
4c6e4df474 (fix): fix org-roam-today date functionality overriding old files (#235) 2020-03-06 19:35:22 +08:00
Jethro Kuan
b1e2209dfc (feature): org-roam-graph-exclude-matcher: exclude nodes from graph (#233) 2020-03-06 12:48:30 +08:00
Anthony Cowley
8f83ffc2a3 org-roam-show-graph: PREFIX to generate a graph but not display it (#232) 
This lets the viewer application watch the file, or have the user manually refresh the view rather than opening a new browser tab.
 2020-03-06 11:22:39 +08:00
Jethro Kuan
09a23c377b (fix): remove nonspacing marks from slugs (#230) 
Linux and macOS use different Unicode normalization conventions in filenames
 2020-03-06 01:47:22 +08:00
Jethro Kuan
d1a47e090e (docs): update docs (#229) 2020-03-06 00:19:11 +08:00
Jethro Kuan
7d1dd831db (fix): relative links should work from org-roam-buffer with multidir (#228) 2020-03-05 13:53:53 +08:00
Jethro Kuan
c77c1b7316 (docs): add more org-protocol instructions for MacOS (#227) 2020-03-05 12:53:57 +08:00
Jethro Kuan
55d7edd5ee (docs): fix org-roam-protocol docs formatting (#226) 2020-03-05 12:07:15 +08:00
Jethro Kuan
1f02b0c5dd (docs): update org-protocol installation for MacOS (#225) 2020-03-05 11:51:28 +08:00
Jethro Kuan
d96ae119ab (bugfix): remove interactive from org-roam-capture (#224) 2020-03-05 11:27:05 +08:00
Jethro Kuan
b7a7741bb0 (feature): use org-capture templates (#216) 
Instead of implementing our own templating system, we abuse org-capture's templating system. We add 2 additional properties:

- :head: a starting template that goes at the beginning of the file.
- :file-name: a string that expands to the file name

The templates are customizable at `org-roam-capture-templates` and `org-roam-ref-capture-templates`.
 2020-03-05 00:21:24 +08:00
Jürgen Hötzel
4de88b3c4f (bugfix): use "org-roam" as graphname (#221) 
The graphname is displayed as tooltip when hovering over non-node
areas in the SVG viewer.

When grahname is undefined Chrome and Firefox just displays
"%3" (ETX/End of Text).
 2020-03-03 21:28:08 +08:00
Jethro Kuan
b74cc14377 (feature): add org-roam-yesterday (#215) 
Closes #214
 2020-03-02 02:53:53 +08:00
Tyler
4c3d5b90a7 (docs): add Doom Emacs installation instructions (#212) 2020-03-01 23:56:05 +08:00
Jethro Kuan
f98e7d22a5 (chore): cleanup and re-order code (#213) 2020-03-01 15:36:39 +08:00
Jethro Kuan
a03ad54460 (bugfix): fix org-roam-delete-file-advice triggering on non-org-roam files (#211) 
Adding a predicate for the delete-file advice ensures that expensive
SQL operations do not run when not necessary
 2020-03-01 02:42:55 +08:00
Jethro Kuan
a88076a704 (fix): build org-roam cache on org-roam-mode (#210) 
`org-roam-build-cache` takes very little time, when the cache is
already built running it on `org-roam-mode` ensures that the cache is
consistent with the files.
 2020-03-01 02:35:01 +08:00
Jethro Kuan
9296470d17 (bugfix): populate database after org-roam--make-new-file (#208) 2020-03-01 01:58:54 +08:00
Jethro Kuan
4da30a7134 (bugfix): escape strings for graph export (#207) 
strings with quotes used to break the graph export. This change escapes the strings.
 2020-03-01 01:08:54 +08:00
Jethro Kuan
150ae65564 (feature): deprecate roam-protocol, extend org-protocol instead (#203) 
Add 2 custom handlers:

1. roam-file?file=path: this simply opens the file at path in Emacs.
2. roam-ref?ref=ref&template=roam-template&title=title&...: attempts to open a roam note with a given ROAM_KEY. If the note doesn't exist, create one. Else, open it.
 2020-02-29 22:09:04 +08:00
Jethro Kuan
0c2aaad3df (feature): use sqlite as backing database (#200) 
All org-roam related information will now be stored in the database. Henceforth, the cache needs to be built synchronously once (via `M-x org-roam-build-cache`), which is then incrementally updated.
 2020-02-29 15:56:08 +08:00
Daniel Koudouna
d086d1675d (fix): change locals to hash tables (#196) 
better support emacs 25
 2020-02-27 10:34:54 +08:00
Jethro Kuan
685aa2afcd Ensure cache consistency for refs cache (#194) 2020-02-26 23:04:02 +08:00
Jethro Kuan
92d25b287e (feature): add a cache for ROAM_KEY (#192) 2020-02-26 22:26:02 +08:00
Jethro Kuan
962ef23cce (fix): Require a minimum version of Org 9.2 for roam link styling (#190) 2020-02-26 16:29:20 +08:00
Jethro Kuan
5e76c67cf6 (feature): emacs-lisp handling for roam:// links (#188) 
We emulate org-protocol, and advise server-find-files, stripping the
roam protocol from the filename. This reduces the setup required to
open `roam://` links.
 2020-02-26 15:35:20 +08:00
Herbert Jones
b382b1f21a (docs): add documentation for multiple org-roam directories (#187) 2020-02-26 15:23:29 +08:00
Jethro Kuan
f1fb9f4680 (docs): remove :after from package install (#186) 
Some of org-roam's functions (e.g. org-roam-today and
org-roam-find-file) should not need to have org loaded before use.
 2020-02-26 11:00:24 +08:00
Jethro Kuan
5b96cf806f (docs): Add documentation for #+ROAM_ALIAS attribute (#185) 2020-02-26 01:33:49 +08:00
Herbert Jones
a8d696e6e8 (performance): avoid path expansion by referencing cache obj (#184) 
Prevent needless repeated calls to org-roam-directory-normalized by having a
reference to the cache object that matches the local buffer.

Co-authored-by: Jethro Kuan <jethrokuan95@gmail.com>
 2020-02-26 00:15:38 +08:00
Jethro Kuan
19f16e9c64 (feature): support file aliases (#182) 
Closes #91
 2020-02-26 00:11:38 +08:00
Jethro Kuan
4b38b07c41 (feature): fix org-roam-open-at-point (#183) 2020-02-25 23:09:37 +08:00
Herbert Jones
b4d89c6a0c (feature): allow multiple org-roam directories (#178) 
Each org-roam-directory gets its own cache. One can override the `org-roam-directory` variable locally via dir-locals:

((org-mode . ((eval . (setq-local org-roam-directory (expand-file-name "./"))))))
 2020-02-25 23:06:40 +08:00
Jethro Kuan
d780b6ffd1 (chore): require minimum org version of 9.0 (#177) 2020-02-24 18:58:03 +08:00
leaen
5f6ff4282c (docs): fix broken markdown src block (#176) 2020-02-24 17:08:29 +08:00
wrycode
a0559a2709 (docs): add note about removing title timestamps in configuration.md (#175) 2020-02-24 14:55:07 +08:00
wrycode
de1ac9d5cc Fix typo in tour.md (#172) 2020-02-24 10:28:16 +08:00
Herbert Jones
b2dc9b33f6 (bugfix): fix new file template default case (#169) 
ref #165

Without this change I am getting the error:

    org-roam--make-new-file: Symbol’s function definition is void: file-name-fn
 2020-02-23 22:54:59 +08:00
Jethro Kuan
f9a903f52d add changelog entry for #165 (#168) 2020-02-23 17:16:57 +08:00
Jethro Kuan
c54c206694 (feature) add templating functionality via org-roam-template (#165) 
This allows users to customize the filename, and the content of the template.
 2020-02-23 17:11:49 +08:00
Herbert Jones
d2843b816f (bugfix): keep unicode alphanumerics in filename (#164) 
Ref #158

Example output:
    (mapcar #'org-roam--title-to-slug
            '("!!!!Org-Roam is great!!!!"
              "Sobre a formação dos planetas"
              "1\\2.3///**"
              "10-2+3=45"))
    ;; ("org_roam_is_great" "sobre_a_formação_dos_planetas" "1_2_3" "10_2_3_45")
 2020-02-23 00:53:16 +08:00
Jürgen Hötzel
c2c25f7d83 (bugfix): Use correct padding for modeline lighter (#163) 2020-02-22 21:40:29 +08:00
Jethro Kuan
cba79b941a (feature): add custom font styling for org-roam links (#162) 
* (feature): add custom font styling for org-roam links

This adds 'org-roam-link-face. When org-roam-mode is on, all roam
links take this face. By default, it is exactly the same as 'org-link,
and would require styling.

* update docs
 2020-02-22 21:11:14 +08:00
Jürgen Hötzel
a2a858a0fe (bugfix): Check future status to prevent multiple async tasks (#160) 
Prevents that the `org-roam--build-cache-async` process is blocked forever if an async
error occurs.

Refs #149, #151
 2020-02-22 16:56:45 +08:00
Jethro Kuan
43ff60fec7 (feature): add org-roam-mute-cache-build to mute cache build message (#159) 2020-02-22 11:29:34 +08:00
Jethro Kuan
fe3f0e3b6c (docs): documentation on how to enable Chrome external app checkbox on Linux (#157) 
* Enable Chrome external app checkbox on Linux

* Fix command to write file
 2020-02-22 11:12:33 +08:00
Herbert Jones
d02d48e559 (bugfix): prevent multiple async build processes (#149) 
Prevent multiple async cache builds.  This can happen when restoring a session
or loading multiple org-roam files before a build has completed.
 2020-02-21 15:45:54 +08:00
Herbert Jones
22f596d275 (feature): update org-roam-insert behaviour on region-selection (#148) 
`org-roam-insert` now uses active region to pre-populate insert completion, and as the link description

fixes #127
 2020-02-21 14:44:43 +08:00
63 changed files with 10663 additions and 2857 deletions
Expand all files Collapse all files

13
.dir-locals.el Normal file
View File

@ -0,0 +1,13 @@
((emacs-lisp-mode
(fill-column . 110)
(indent-tabs-mode . nil)
(elisp-lint-ignored-validators . ("byte-compile" "package-lint"))
(elisp-lint-indent-specs . ((describe . 1)
(it . 1)
(org-element-map . defun)
(org-roam-with-temp-buffer . 1)
(org-with-point-at . 1)
(magit-insert-section . defun)
(magit-section-case . 0)
(->> . 1)
(org-roam-with-file . 2)))))

12
.github/FUNDING.yml vendored Normal file
View File

@ -0,0 +1,12 @@
# These are supported funding model platforms
github: [jethrokuan, zaeph]
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

23
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -1,14 +1,15 @@
---
name: Bug Report
about: Something's not working.
title: ''
labels: ''
assignees: 'jethrokuan'
title: ""
labels: ""
assignees: ""
---
### Description
#### Steps to Reproduce
<!--
Example:
@ -18,13 +19,25 @@ Example:
...
-->
#### Backtrace
<!--
Will help us track and understand issues faster.
How to provide a backtrace:
1. M-x toggle-debug-on-error
2. Trigger error. The debugger buffer should pop up.
3. Copy the contents of the debugger buffer and paste here
-->
#### Expected Results
<!-- Example: File A is there -->
#### Actual Results
<!-- Example: File A is missing -->
### Versions
- Emacs (`C-h v emacs-version`): vX.X.X
### Environment
<!-- Please M-x org-roam-diagnostics and paste results here -->
- Org-roam commit: https://github.com/jethrokuan/org-roam/commit/commithashhere

7
.github/ISSUE_TEMPLATE/feature_request.md vendored
View File

@ -1,9 +1,9 @@
---
name: Feature Request
about: Create a feature request to improve Org-roam
title: ''
labels: 'enhancement'
assignees: 'jethrokuan'
title: ""
labels: "enhancement"
assignees: ""
---
### Brief Abstract
@ -13,4 +13,5 @@ assignees: 'jethrokuan'
### Proposed Implementation (if any)
### Please check the following:
- [ ] No similar feature requests

31
.github/workflows/docs.yml vendored Normal file
View File

@ -0,0 +1,31 @@
# * docs.yml --- Build the documentation and publish to Github Pages
name: "Docs"
on:
push:
branches:
- master
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: true
steps:
- uses: actions/checkout@v2
- name: Install deps
run: |
sudo apt-get install texinfo
- name: Build docs
continue-on-error: false
run: make html
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages # The branch the action should deploy to.
FOLDER: doc # The folder the action should deploy.
CLEAN: true

22
.github/workflows/test.yml vendored
View File

@ -29,16 +29,14 @@ on:
push:
branches:
- master
- develop
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
emacs_version:
- 26.3
- 27.1
- snapshot
steps:
- uses: purcell/setup-emacs@master
@ -47,23 +45,17 @@ jobs:
- uses: actions/checkout@v2
- name: Initialize sandbox
run: |
SANDBOX_DIR=$(mktemp -d) || exit 1
echo ::set-env name=SANDBOX_DIR::$SANDBOX_DIR
./makem.sh -vv --sandbox $SANDBOX_DIR --install-deps --install-linters
- name: Install Eldev
run: curl -fsSL https://raw.github.com/doublep/eldev/master/webinstall/github-eldev | sh
# The "all" rule is not used, because it treats compilation warnings
# as failures, so linting and testing are run as separate steps.
- name: Install dependencies
run: make prepare
- name: Lint
continue-on-error: true
run: ./makem.sh -vv --sandbox $SANDBOX_DIR lint
run: make lint
- name: Test
if: always() # Run test even if linting fails.
run: ./makem.sh -vv --sandbox $SANDBOX_DIR test
run: make test
# Local Variables:
# eval: (outline-minor-mode)
# End:

14
.gitignore vendored
View File

@ -1,2 +1,16 @@
/.sandbox/
**/*.elc
/doc/dir
/doc/*.info
/doc/*.pdf
/doc/*.epub
/doc/META_INF/
/doc/OEBPS/
/doc/dir
/doc/epub.xml
/doc/org-roam/
/doc/mimetype
/doc/stats/
/config.mk
/doc/manual.html
/.eldev/

8
.readthedocs.yml
View File

@ -1,8 +0,0 @@
version: 2
mkdocs:
configuration: mkdocs.yml
formats: all
python:
version: 3.7
install:
- requirements: doc/requirements.txt

8
BACKERS.md Normal file
View File

@ -0,0 +1,8 @@
# Backers
Many thanks to the following backers, your contributions are greatly appreciated!
- Nathan Tran
- Burke Libbey
- forkrul
- Andreas Stuhlmüller

427
CHANGELOG.md
View File

@ -1,93 +1,394 @@
# Changelog
## TBD
### Added
### Removed
### Changed
- [#1795](https://github.com/org-roam/org-roam/pull/1795) buffer: optimized reflinks fetch
### Fixed
## 2.1.0
### Added
- [#1709](https://github.com/org-roam/org-roam/pull/1709) added ability to specify default value in org-roam capture templates
- [#1710](https://github.com/org-roam/org-roam/pull/1710) added `org-roam-extract-subtree`
- [#1720](https://github.com/org-roam/org-roam/pull/1720) added `org-roam-db-update-on-save`
- [#1758](https://github.com/org-roam/org-roam/pull/1758) added `org-roam-db-autosync-mode`, replacing `org-roam-setup` and `org-roam-teardown`
### Removed
- [#1716](https://github.com/org-roam/org-roam/pull/1716) helper function `org-roam-get-keyword` is now obsolete: prefer `org-collect-keywords`
### Changed
- [#1595](https://github.com/org-roam/org-roam/pull/1595), [#1724](https://github.com/org-roam/org-roam/pull/1724) Major refactoring and restructuring of the codebase
- [#1655](https://github.com/org-roam/org-roam/pull/1655) improved org-roam contents preview
- [#1741](https://github.com/org-roam/org-roam/pull/1741) expose `org-roam-capture-` keys in interactive commands
- [#1786](https://github.com/org-roam/org-roam/pull/1786) org-roam-version now outputs commit hash if found
- [#1788](https://github.com/org-roam/org-roam/pull/1788) the point is not moved if the node is already visited
### Fixed
- [#1608](https://github.com/org-roam/org-roam/pull/1608) migration: empty ROAM_REFS are now removed
- [#1609](https://github.com/org-roam/org-roam/pull/1609) migration: fixed file-link replacement
- [#1653](https://github.com/org-roam/org-roam/pull/1653) migration: fixed tags migration
- [#1694](https://github.com/org-roam/org-roam/pull/1694) core: nodes with no title are now skipped
- [#1637](https://github.com/org-roam/org-roam/pull/1637) core: fix org-ref multi-cite links not being split
- [#1651](https://github.com/org-roam/org-roam/pull/1651) core: fix org-roam-file-p crashing when there is no corresponding file
- [#1705](https://github.com/org-roam/org-roam/pull/1705) core: fix for add/remove of file-level tags
- [#1769](https://github.com/org-roam/org-roam/pull/1769) core: gracefully handle absence of `org-id-locations-file`
- [#1713](https://github.com/org-roam/org-roam/pull/1713) capture: check for file-existence before template insertion
- [#1725](https://github.com/org-roam/org-roam/pull/1725) db: always compute hash of encrypted file to prevent re-processing of encrypted files
## 2.0.0
### Added
- [#1396](https://github.com/org-roam/org-roam/pull/1396) add option to choose between prepending, appending, and omitting `roam_tags` in file completion
- [#1270](https://github.com/org-roam/org-roam/pull/1270) capture: create OLP if it does not exist. Removes need for OLP setup in `:head`.
- [#1353](https://github.com/org-roam/org-roam/pull/1353) support file-level property drawers
### Changed
- [#1352](https://github.com/org-roam/org-roam/pull/1352) prefer lower-case for roam_tag and roam_alias in interactive commands
- [#1513](https://github.com/org-roam/org-roam/pull/1513) replaced hardcoded "svg" with defcustom org-roam-graph-filetype
- [#1540](https://github.com/org-roam/org-roam/pull/1540) allow `roam_tag` and `roam_alias` to be specified on multiple lines
### Fixed
- [#1281](https://github.com/org-roam/org-roam/pull/1281) fixed idle-timer not instantiated on `org-roam-mode`
- [#1308](https://github.com/org-roam/org-roam/pull/1308) fixed file renames corrupting database
- [#1325](https://github.com/org-roam/org-roam/pull/1325) make titles and tags extracted unique per note
- [#1327](https://github.com/org-roam/org-roam/pull/1327) preserve existing link description during automatic replacement
- [#1346](https://github.com/org-roam/org-roam/pull/1346) prevent malformed path to `org-roam-index-file`
- [#1347](https://github.com/org-roam/org-roam/pull/1347) allow use of `%a` element in regular Org-roam captures
- [#1352](https://github.com/org-roam/org-roam/pull/1352) fixed org-roam-{tag/alias}-{add/delete} altering the original case of the Org property
- [#1374](https://github.com/org-roam/org-roam/pull/1374) fix headline completions erroring out
- [#1375](https://github.com/org-roam/org-roam/pull/1375) fix org-roam-protocol to use existing ref file
- [#1403](https://github.com/org-roam/org-roam/issues/1403) fixed inconsistency between how we write and read props like alias and tags
- [#1409](https://github.com/org-roam/org-roam/issues/1398) prevent inclusion of non-org-roam files in `org-roam-dailies--list-files`
- [#1542](https://github.com/org-roam/org-roam/issues/1542) fix files not excluded when `org-roam-list-files-commands` is nil
## 1.2.3 (13-11-2020)
Primarily a stabilization and bug-fix release.
Org-roam-dailies has also been revamped to include new features, see [this video](https://www.youtube.com/watch?v=1q9x2aZCJJ4) for a quick overview.
### Added
- [#978](https://github.com/org-roam/org-roam/pull/978) Revamp org-roam-dailies
- [#1183](https://github.com/org-roam/org-roam/pull/1183) Interactive functions for managing aliases and tags in Org-roam file, namely `org-roam-alias-add`, `org-roam-alias-delete`, `org-roam-tag-add`, and `org-roam-tag-delete`.
- [#1215](https://github.com/org-roam/org-roam/pull/1215) Multiple `ROAM_KEY` keywords can now be specified in one file. This allows bibliographical entries to share the same note file.
- [#1238](https://github.com/org-roam/org-roam/pull/1238) Add `org-roam-prefer-id-links` variable to select linking method
- [#1239](https://github.com/org-roam/org-roam/pull/1239) Allow `org-roam-protocol` to capture the webpage's selection, and add a toggle for storing the links to the pages
- [#1264](https://github.com/org-roam/org-roam/pull/1264) add `org-roam-db-update-method` to control when the cache is rebuilt.
### Changed
- [#1264](https://github.com/org-roam/org-roam/pull/1264) renamed `org-roam-update-db-idle-seconds` to `org-roam-db-idle-idle-seconds`
### Fixed
- [#1074](https://github.com/org-roam/org-roam/issues/1074) fix `org-roam--extract-links` to handle content boundaries.
- [#1193](https://github.com/org-roam/org-roam/issues/1193) fix `org-roam-db-build-cache` by not killing temporary buffer in `org-roam--extract-links`.
- [#1195](https://github.com/org-roam/org-roam/issues/1195) fix ID face showing as invalid if within Org ID files, but not Org-roam's.
- [#1199](https://github.com/org-roam/org-roam/issues/1199) make Org-roam link insertions respect `org-roam-link-title-format` everywhere.
- [#1201](https://github.com/org-roam/org-roam/issues/1201) fix `org-roam-db-build-cache` failing in scenarios involving duplicate IDs and deleted files.
- [#1226](https://github.com/org-roam/org-roam/issues/1226) only update relative path of file links
- [#1232](https://github.com/org-roam/org-roam/issues/1232) fix incorrect title extractions from narrowed buffers
- [#1233](https://github.com/org-roam/org-roam/issues/1233) fixes bug where descriptive file links become plain links during update for relative paths
- [#1252](https://github.com/org-roam/org-roam/issues/1252) respect original link type during automatic replacement
## 1.2.2 (06-10-2020)
In this release we support fuzzy links of the form `[[roam:Title]]`, `[[roam:*Headline]]` and `[[roam:Title*Headline]]`. Completion for these fuzzy links is supported via `completion-at-point`.
Org-roam now does not resolve symlinks. This significantly speeds up cache builds, but may result in some workflows breaking. In particular, Org-roam now cannot figure out if two distinct file paths in the Org-roam directory are the same file, and both files will be processed as if they were different files. This error seems to be unavoidable now that symlinks are not resolved, but this workflow is rare and should not affect most users.
This change requires you to set `org-roam-directory` to the resolved path of a folder. That is:
```elisp
(setq org-roam-directory (file-truename "/path/to/directory/"))
```
### Breaking Changes
- [#1164](https://github.com/org-roam/org-roam/pull/1164) Org-roam now stores the database in the user's Emacs directory by default
- [#910](https://github.com/org-roam/org-roam/pull/910) Deprecate `company-org-roam`, using `completion-at-point` instead. To use this with company, add the `company-capf` backend instead.
- [#1109](https://github.com/org-roam/org-roam/pull/1109) Org-roam now does not resolve symlinks.
### Features
- [#1163](https://github.com/org-roam/org-roam/pull/1163) Support file-level IDs introduced in Org 9.4
- [#1093](https://github.com/org-roam/org-roam/pull/1093) Add `vanilla` org-roam-tag-source to extract buffer Org tags
- [#1079](https://github.com/org-roam/org-roam/pull/1079) Add `org-roam-tag-face` to customize appearance of tags in interactive commands
- [#1073](https://github.com/org-roam/org-roam/pull/1073) Rename file on title change, when `org-roam-rename-file-on-title-change` is non-nil.
- [#1071](https://github.com/org-roam/org-roam/pull/1071) Update link descriptions on title changes, and clean-up rename file advice
- [#1061](https://github.com/org-roam/org-roam/pull/1061) Speed up the extraction of file properties, headlines, and titles
- [#1046](https://github.com/org-roam/org-roam/pull/1046) New user option to exclude files from Org-roam
- [#1032](https://github.com/org-roam/org-roam/pull/1032) File changes are now propagated to the database on idle timer. This prevents large wait times during file saves.
- [#974](https://github.com/org-roam/org-roam/pull/974) Protect region targeted by `org-roam-insert`
- [#994](https://github.com/org-roam/org-roam/pull/994) Simplify org-roam-store-link
- [#1062](https://github.com/org-roam/org-roam/pull/1062) Variable `org-roam-completions-everywhere` allows for completions everywhere from word at point
- [#910](https://github.com/org-roam/org-roam/pull/910), [#1105](https://github.com/org-roam/org-roam/pull/1105) Support fuzzy links of the form `[[roam:Title]]`, `[[roam:*Headline]]` and `[[roam:Title*Headline]]`
### Bugfixes
- [#1057](https://github.com/org-roam/org-roam/pull/1057) Improve performance of database builds by preventing generation of LaTeX and image previews.
- [#1103](https://github.com/org-roam/org-roam/pull/1103) Fix long build-times for Windows on files with URL links
## 1.2.1 (27-07-2020)
This release consisted of a big deal of refactoring and bug fixes. Notably, we fixed several catastrophic failures on db builds with bad setups (#854), and modularized tag and title extractions.
We also added some new features that had been a long time coming:
1. We made the backlinks more outline-friendly by also showing the outline hierarchy for a backlink (#863)
2. We now support nested captures, which is crucial for `org-roam-protocol` (#966)
### Breaking Changes
- [#908](https://github.com/org-roam/org-roam/pull/908) Normalized titles in database. May break external packages that rely on unnormalized titles.
### Features
- [#814](https://github.com/org-roam/org-roam/pull/814) Implement `org-roam-insert-immediate`
- [#833](https://github.com/org-roam/org-roam/pull/833) Add customization of file titles with `org-roam-title-to-slug-function`.
- [#839](https://github.com/org-roam/org-roam/pull/839) Return selected file from `org-roam-insert`
- [#847](https://github.com/org-roam/org-roam/pull/847) Add GC threshold `org-roam-db-gc-threshold` to temporarily change the threshold on expensive operations.
- [#847](https://github.com/org-roam/org-roam/pull/847) Use sqlite3 transactions instead of storing the values to be inserted.
- [#851](https://github.com/org-roam/org-roam/pull/851) Add `'first-directory'` option for `org-roam-tag-sources`
- [#863](https://github.com/org-roam/org-roam/pull/863) Display outline hierarchy in backlinks buffer
- [#898](https://github.com/org-roam/org-roam/pull/898) Add `org-roam-random-note` to browse a random note.
- [#900](https://github.com/org-roam/org-roam/pull/900) Support and index all valid org links
- [#966](https://github.com/org-roam/org-roam/pull/966) Enable nested captures
### Bugfixes
- [#854](https://github.com/org-roam/org-roam/pull/854) Warn instead of fail when duplicate refs and IDs exist.
- [#857](https://github.com/org-roam/org-roam/pull/857) Fix tag extraction for symlinked directories.
- [#894](https://github.com/org-roam/org-roam/pull/894) Perform link fixes on all Org-roam files
- [#952](https://github.com/org-roam/org-roam/pull/952) Cache `${foo}` template variables so they do not need to be re-entered twice
## 1.2.0 (12-06-2020)
In this release, we improved the linking process by achieving feature parity between links to files and links to headlines. Before, we used the `file:foo::*bar` format to link to the headline `bar` in file `foo`, but this was prone to breakage upon renaming the file or modifying the headline. This is not the case anymore. Now, we use `org-id` to create IDs for those headlines, which are then stored in our database to compute the relationships and jump around. Note that this will work even if you’re not using `org-id` in your global configuration for Org-mode.
This is a major step forward. Supporting the in-file structure of Org-mode files means that we can interface with many of its core-features like TODOs, properties, priorities, etc. UX will have to be figured out, but this release ushers in a new age in terms of functionalities.
We also add `org-roam-unlinked-references`, which naively finds text that could be references to the current Org-roam file.
### Breaking Changes
- [#701](https://github.com/org-roam/org-roam/pull/701) Use `emacsql-sqlite3` instead of `emacsql-sqlite` for better Windows compatibility. This requires the presence of the standard `sqlite3` binary on your machine.
- [#750](https://github.com/org-roam/org-roam/pull/750) Deprecate `org-roam-buffer-no-delete-other-windows` in favour of `org-roam-buffer-window-parameters`.
### Features
- [#787](https://github.com/org-roam/org-roam/pull/787) Add `org-roam-unlinked-references`
- [#783](https://github.com/org-roam/org-roam/pull/783) Add support for headlines
- [#757](https://github.com/org-roam/org-roam/pull/757) Roam global properties are now case-insensitive
- [#680](https://github.com/org-roam/org-roam/pull/680) , [#703](https://github.com/org-roam/org-roam/pull/703), [#708](https://github.com/org-roam/org-roam/pull/708) Add `org-roam-doctor` checkers for `ROAM_*` properties
- [#664](https://github.com/org-roam/org-roam/pull/664) Add support for shelling out to `rg` and `find` in `org-roam--list-files`
- [#679](https://github.com/org-roam/org-roam/pull/679), [#683](https://github.com/org-roam/org-roam/pull/683) Building of the graph now happens in a separate process
### Bugfixes
- [#714](https://github.com/org-roam/org-roam/pull/714) No longer print citelinks in backlinks buffer if there is no `ROAM_KEY` property or `org-ref` is not installed
- [#759](https://github.com/org-roam/org-roam/pull/759), [#760](https://github.com/org-roam/org-roam/pull/760) Tags are only added to the tags table if there are actually tags present
- [#700](https://github.com/org-roam/org-roam/pull/700), [#733](https://github.com/org-roam/org-roam/pull/733) Allow symlinks within the `org-roam` directory
## 1.1.1 (18-05-2020)
In this release, we added two new features:
1. `org-roam-doctor`: a linting system that helps you discover possible problems with your Org-roam files. This is in the spirit of keeping notes in top quality.
2. A tagging system: one can now use sub-directories, and the `#+roam_tags` key add additional meta data to notes. For more information, see [here](https://www.orgroam.com/manual/Tags.html#Tags).
As usual, this release comes with a multitude of bug-fixes and refactorings.
### Breaking Changes
- [#523](https://github.com/org-roam/org-roam/pull/523) remove `org-roam-completion-fuzzy-match` in favor of using completion mechanism's configuration options directly
- [#547](https://github.com/org-roam/org-roam/pull/547) Deprecate `org-roam-db--maybe-update`, in favour of `org-roam-db--update-maybe`
- [#604](https://github.com/org-roam/org-roam/pull/604) Deprecate `org-roam-title-include-subdirs`, `org-roam-title-subdir-format` `org-roam-title-subdir-separator`, for a more general tagging system built on subdirectories
### Bugfixes
- [#509](https://github.com/org-roam/org-roam/pull/509) fix backup files being tracked in database
- [#509](https://github.com/org-roam/org-roam/pull/509) fix external org files being tracked in database
- [#537](https://github.com/org-roam/org-roam/pull/537) quote graphviz node and edge configuration options to allow multi-word configurations
- [#545](https://github.com/org-roam/org-roam/pull/545) fix `org-roam--extract-links` to ensure that multiple citations (`cite:key1,key2`) are split correctly
- [#547](https://github.com/org-roam/org-roam/pull/547) Fix unlinked citations
- [#660](https://github.com/org-roam/org-roam/pull/660) fix rename-file advice not working for renaming to directories
- [#660](https://github.com/org-roam/org-roam/pull/660) fix links breaking within file on file movement
### Features
- [#538](https://github.com/org-roam/org-roam/pull/538) Optionally use text in first headline as title
- [#553](https://github.com/org-roam/org-roam/pull/553) Add prefix argument to `org-roam-db-build-cache` for forcing rebuilds
- [#560](https://github.com/org-roam/org-roam/pull/560) Apply 'error face to distinguish broken links
- [#570](https://github.com/org-roam/org-roam/pull/570) Add `org-roam-doctor` to diagnose org-roam files
- [#625](https://github.com/org-roam/org-roam/pull/625) Add `org-roam-title-sources` to control how titles are retrieved within notes
- [#604](https://github.com/org-roam/org-roam/pull/604) Add a tagging system. `org-roam-tag-sources` controls how tags are retrieved from notes
### Internal Changes
- [#547](https://github.com/org-roam/org-roam/pull/547) Added `type` column to the `refs` table
- [#606](https://github.com/org-roam/org-roam/pull/606) Added `org-roam-dev.el` for developer coding standards
- [#622](https://github.com/org-roam/org-roam/pull/622) Online documentation now points to the Org-based documentation
## 1.1.0 (21-04-2020)
To the average user, this release is mainly a bugfix release with additional options to customize. However, the changes made to the source is significant. Most notably, in this release:
1. The codebase has been modularized into separate files, to ease future maintenance and adding of new features (mainly by [@progfolio](https://github.com/progfolio)). Because of these changes, we had to rename many functions and variables: the old names are kept for backwards compatibility, but you are encouraged to use the new function names. You'll receive a warning when you're calling the function with its obsolete name.
2. [@kljohann](https://github.com/kljohann) did some fantastic work on graph generation: allowing building images for connected components within the graph up to a specified distance
3. We also started supporting `org-ref` natively: cite links now show up in both the graph and the org-roam buffer.
In the coming months, you can expect work on bigger projects (e.g. revamping the org-roam buffer).
### Breaking Changes
- [#385](https://github.com/org-roam/org-roam/pull/385) Deprecate `org-roam-graph-node-shape` in favour of `org-roam-graph-node-extra-config`.
- [#473](https://github.com/org-roam/org-roam/pull/473) Deprecate `org-roam-date-filename-format` and `org-roam-date-title-format`, in favour of `org-roam-dailies-capture-templates`.
### New Features
- [#350](https://github.com/org-roam/org-roam/pull/350) Add `org-roam-db-location` to customize location of org-roam database.
- [#359](https://github.com/org-roam/org-roam/pull/359) Add `org-roam-verbose` to allow or silence printing of information.
- [#374](https://github.com/org-roam/org-roam/pull/374) Add support for `org-ref` `cite:` links
- [#380](https://github.com/org-roam/org-roam/pull/380) Allow `org-roam-buffer-position` to also be `top` or `bottom`
- [#385](https://github.com/org-roam/org-roam/pull/385) Add `org-roam-graph-node-extra-config` to configure Graphviz nodes
- [#398](https://github.com/org-roam/org-roam/pull/398), [#418](https://github.com/org-roam/org-roam/pull/418) Add graph building for connected components
- [#435](https://github.com/org-roam/org-roam/pull/435) Add `org-roam-graph-edge-extra-config` to configure Graphviz edges
- [#439](https://github.com/org-roam/org-roam/pull/439) Add support for `org-ref` citations to display as edges in graph. Add `org-roam-graph-edge-cites-extra-config` to configure these edges
- [#465](https://github.com/org-roam/org-roam/pull/465) Add `org-roam-file-extensions` to allow detection of org files with different file extensions
- [#488](https://github.com/org-roam/org-roam/pull/488) Allow a function for `org-roam-graph-viewer`
- [#491](https://github.com/org-roam/org-roam/pull/491) Use TITLE as description when linking before first heading
### Bugfixes
- [#470](https://github.com/org-roam/org-roam/pull/470) Add workaround for undocumented `file-truename` behaviour in `org-roam--org-roam-file-p`.
### Internal Changes
- [#363](https://github.com/org-roam/org-roam/pull/363), [#473](https://github.com/org-roam/org-roam/pull/473) Modularize org-roam features.
- [#497](https://github.com/org-roam/org-roam/pull/497) Simplify `org-roam--list-files` implementation
## 1.0.0 (23-03-2020)
Org-roam is now on MELPA! We have squashed most of the bugs, and Org-roam has
been stable for the most part.
### New Features
- [#269](https://github.com/org-roam/org-roam/pull/269) Add `org-roam-graphviz-extra-options`
- [#257](https://github.com/org-roam/org-roam/pull/257) Add a company-backend `company-org-roam`
- [#284](https://github.com/org-roam/org-roam/pull/284), [#289](https://github.com/org-roam/org-roam/pull/289) Configurable `org-roam-completion-system` with options `'default`, `'ido`, `'ivy` and `'helm`
- [#289](https://github.com/org-roam/org-roam/pull/289) Add customizable `org-roam-fuzzy-match` to allow fuzzy-matching of candidates
- [#290](https://github.com/org-roam/org-roam/pull/290) Add `org-roam-date-title-format` and `org-roam-date-filename-format` for customizing Org-roam's date files
- [#296](https://github.com/org-roam/org-roam/pull/296) Allow multiple exclusion matchers in `org-roam-graph-exclude-matcher`
### Bugfixes
- [#293](https://github.com/org-roam/org-roam/pull/293) Fix capture templates not working as expected for `org-roam-find-file`
- [#275](https://github.com/org-roam/org-roam/pull/275) Fix database rebuild when `org-roam-directory` is set locally
## 1.0.0-rc1 (06-03-2020)
This is a pre-release before the push to MELPA. It contains large
internal changes, with little user-facing changes. Most notably, the
backing storage has been changed to a SQLite database, and a
templating system using `org-capture` is introduced.
### Breaking Changes
- [#200](https://github.com/org-roam/org-roam/pull/200) Move Org-roam cache into a SQLite database.
- [#203](https://github.com/org-roam/org-roam/pull/203) Roam protocol is deprecated, in favour of extending org-roam-protocol.
### New Features
- [#182](https://github.com/org-roam/org-roam/pull/182) Support file name aliases via `#+ROAM_ALIAS`.
- [#216](https://github.com/org-roam/org-roam/pull/216) Adds templating functionality by extending org-capture.
- [#232](https://github.com/org-roam/org-roam/pull/232) Adds a prefix key to `org-roam-show-graph`, to generate graph without opening it.
- [#233](https://github.com/org-roam/org-roam/pull/233) Adds `org-roam-graph-exclude-matcher`, which allows exclusion of nodes from graph.
- [#247](https://github.com/org-roam/org-roam/pull/247) Add `org-roam-backlink` face, which allows customizing backlinks appearance
- [#259](https://github.com/org-roam/org-roam/pull/259) Add optional initial-prompt to `org-roam-find-file`
### Bugfixes
- [#207](https://github.com/org-roam/org-roam/pull/207), [#221](https://github.com/org-roam/org-roam/pull/221) small bugfixes to Org-roam graph generation
- [#230](https://github.com/org-roam/org-roam/pull/230) remove nonspacing marks from filenames, to prevent cross-platform errors
### New Contributors
- [@acowley][https://github.com/acowley]
- [@teesloane][https://github.com/teesloane]
## 0.1.2 (2020-02-21)
### Breaking Changes
* [#143][gh-143] `org-roam-mode` is now a global mode. The installation instructions have changed accordingly.
* [#103][gh-103] Change `org-roam-file-format` to a function: `org-roam-file-name-function` to allow more flexible file name customizaton. Also changes `org-roam-use-timestamp-as-filename` to `org-roam-filename-noconfirm` to better describe what it does.
- [#143](https://github.com/org-roam/org-roam/pull/143) `org-roam-mode` is now a global mode. The installation instructions have changed accordingly.
- [#103](https://github.com/org-roam/org-roam/pull/103) Change `org-roam-file-format` to a function: `org-roam-file-name-function` to allow more flexible file name customizaton. Also changes `org-roam-use-timestamp-as-filename` to `org-roam-filename-noconfirm` to better describe what it does.
### New Features
* [#145][gh-145] `org-roam-show-graph`: Fallback to Emacs SVG viewer
* [#141][gh-141] add variable `org-roam-new-file-directory` for new Org-roam files
* [#138][gh-138] add `org-roam-switch-to-buffer`
* [#124][gh-124], [#141][gh-141] Maintain cache consistency on file rename and delete
* [#87][gh-87], [#90][gh-90] Support encrypted Org files
* [#110][gh-110] Add prefix to `org-roam-insert`, for inserting titles down-cased
* [#99][gh-99] Add keybinding so that `<return>` or `mouse-1` in the backlinks buffer visits the source file of the backlink at point
- [#145](https://github.com/org-roam/org-roam/pull/145) `org-roam-show-graph`: Fallback to Emacs SVG viewer
- [#141](https://github.com/org-roam/org-roam/pull/141) add variable `org-roam-new-file-directory` for new Org-roam files
- [#138](https://github.com/org-roam/org-roam/pull/138) add `org-roam-switch-to-buffer`
- [#124](https://github.com/org-roam/org-roam/pull/124), [#141](https://github.com/org-roam/org-roam/pull/141) Maintain cache consistency on file rename and delete
- [#87](https://github.com/org-roam/org-roam/pull/87), [#90](https://github.com/org-roam/org-roam/pull/90) Support encrypted Org files
- [#110](https://github.com/org-roam/org-roam/pull/110) Add prefix to `org-roam-insert`, for inserting titles down-cased
- [#99](https://github.com/org-roam/org-roam/pull/99) Add keybinding so that `<return>` or `mouse-1` in the backlinks buffer visits the source file of the backlink at point
### Changes
* [#108][gh-108] Locally overwrite the link following behaviour in the org-roam-buffer to open files in the same window `org-roam` was called from
- [#108](https://github.com/org-roam/org-roam/pull/108) Locally overwrite the link following behaviour in the org-roam-buffer to open files in the same window `org-roam` was called from
### Bugfixes
* [#86][gh-86] Fix `org-roam--parse-content` incorrect `:to` computation for nested files
* [#98][gh-98] Fix `org-roam--find-file` picking up temporary files
* [#136][gh-136] Misc bugfixes
- [#86](https://github.com/org-roam/org-roam/pull/86) Fix `org-roam--parse-content` incorrect `:to` computation for nested files
- [#98](https://github.com/org-roam/org-roam/pull/98) Fix `org-roam--find-file` picking up temporary files
- [#136](https://github.com/org-roam/org-roam/pull/136) Misc bugfixes
### Internal
* [#122][gh-122], [#128][gh-128] Improve performance of post-command-hook
* [#92][gh-92], [#105][gh-105] Add tests for core functionality
- [#122](https://github.com/org-roam/org-roam/pull/122), [#128](https://github.com/org-roam/org-roam/pull/128) Improve performance of post-command-hook
- [#92](https://github.com/org-roam/org-roam/pull/92), [#105](https://github.com/org-roam/org-roam/pull/105) Add tests for core functionality
### New Contributors
* [@frigge](https://github.com/frigge)
* [@juergenhoetzel](https://github.com/juergenhoetzel)
* [@chip2n](https://github.com/chip2n)
* [@l3kn](https://github.com/l3kn)
* [@jdormit](https://github.com/jdormit)
* [@herbertjones](https://github.com/herbertjones)
* [@CeleritasCelery](https://github.com/CeleritasCelery)
* [@daniel-koudouna](https://github.com/daniel-koudouna)
- [@frigge](https://github.com/frigge)
- [@juergenhoetzel](https://github.com/juergenhoetzel)
- [@chip2n](https://github.com/chip2n)
- [@l3kn](https://github.com/l3kn)
- [@jdormit](https://github.com/jdormit)
- [@herbertjones](https://github.com/herbertjones)
- [@CeleritasCelery](https://github.com/CeleritasCelery)
- [@daniel-koudouna](https://github.com/daniel-koudouna)
## 0.1.1 (2020-02-15)
Mostly a documentation/cleanup release.
### New Features
* [#62][gh-62] Add the options `org-roam-use-timestamps-as-filename` and `org-roam-file-format`, more in documentation.
- [#62](https://github.com/org-roam/org-roam/pull/62) Add the options `org-roam-use-timestamps-as-filename` and `org-roam-file-format`, more in documentation.
### Breaking Changes
* [#62][gh-62] The ID (file-name) workflow is no longer first-class, but a fallback when titles don't exist.
- [#62](https://github.com/org-roam/org-roam/pull/62) The ID (file-name) workflow is no longer first-class, but a fallback when titles don't exist.
### Changes
* [#66][gh-66], [#68][gh-68]: Improved the quality of the package in preparation of submission to MELPA
* [#73][gh-73]: Added CI to the project via Github Issues (Thanks [@alphapapa](https://github.com/alphapapa/) for scripts and setup)
* [#69][gh-69], [#72][gh-72], [#75][gh-75]: Major cleanup and de-duplication of code
- [#66](https://github.com/org-roam/org-roam/pull/66), [#68](https://github.com/org-roam/org-roam/pull/68): Improved the quality of the package in preparation of submission to MELPA
- [#73](https://github.com/org-roam/org-roam/pull/73): Added CI to the project via Github Issues (Thanks [@alphapapa](https://github.com/alphapapa/) for scripts and setup)
- [#69](https://github.com/org-roam/org-roam/pull/69), [#72](https://github.com/org-roam/org-roam/pull/72), [#75](https://github.com/org-roam/org-roam/pull/75): Major cleanup and de-duplication of code
### Bugfixes
* [#67][gh-67]: Fixed `org-roam--make-file` not creating files with extensions
* [#71][gh-71], [#78][gh-78]: Fixed `org-roam-insert` not inserting correct paths
* [#82][gh-82]: Fixed nested Org-roam files not being detected as part of Org-roam
[gh-62]: https://github.com/jethrokuan/org-roam/pull/66
[gh-66]: https://github.com/jethrokuan/org-roam/pull/66
[gh-67]: https://github.com/jethrokuan/org-roam/pull/67
[gh-68]: https://github.com/jethrokuan/org-roam/pull/68
[gh-69]: https://github.com/jethrokuan/org-roam/pull/69
[gh-71]: https://github.com/jethrokuan/org-roam/pull/71
[gh-72]: https://github.com/jethrokuan/org-roam/pull/72
[gh-73]: https://github.com/jethrokuan/org-roam/pull/73
[gh-75]: https://github.com/jethrokuan/org-roam/pull/75
[gh-78]: https://github.com/jethrokuan/org-roam/pull/78
[gh-82]: https://github.com/jethrokuan/org-roam/pull/82
[gh-86]: https://github.com/jethrokuan/org-roam/pull/86
[gh-87]: https://github.com/jethrokuan/org-roam/pull/87
[gh-90]: https://github.com/jethrokuan/org-roam/pull/90
[gh-92]: https://github.com/jethrokuan/org-roam/pull/92
[gh-98]: https://github.com/jethrokuan/org-roam/pull/98
[gh-99]: https://github.com/jethrokuan/org-roam/pull/99
[gh-103]: https://github.com/jethrokuan/org-roam/pull/103
[gh-105]: https://github.com/jethrokuan/org-roam/pull/105
[gh-108]: https://github.com/jethrokuan/org-roam/pull/108
[gh-110]: https://github.com/jethrokuan/org-roam/pull/110
[gh-122]: https://github.com/jethrokuan/org-roam/pull/122
[gh-124]: https://github.com/jethrokuan/org-roam/pull/124
[gh-128]: https://github.com/jethrokuan/org-roam/pull/128
[gh-136]: https://github.com/jethrokuan/org-roam/pull/136
[gh-138]: https://github.com/jethrokuan/org-roam/pull/138
[gh-141]: https://github.com/jethrokuan/org-roam/pull/141
[gh-142]: https://github.com/jethrokuan/org-roam/pull/142
[gh-143]: https://github.com/jethrokuan/org-roam/pull/143
- [#67](https://github.com/org-roam/org-roam/pull/67): Fixed `org-roam--make-file` not creating files with extensions
- [#71](https://github.com/org-roam/org-roam/pull/71), [#78](https://github.com/org-roam/org-roam/pull/78): Fixed `org-roam-insert` not inserting correct paths
- [#82](https://github.com/org-roam/org-roam/pull/82): Fixed nested Org-roam files not being detected as part of Org-roam
# Local Variables:
# eval: (auto-fill-mode -1)
# End:
<!-- Local Variables: -->
<!-- eval: (auto-fill-mode -1) -->
<!-- End: -->

29
Eldev Normal file
View File

@ -0,0 +1,29 @@
; -*- mode: emacs-lisp; lexical-binding: t; no-byte-compile: t -*-
;; explicitly set main file
(setf eldev-project-main-file "org-roam.el")
(eldev-use-package-archive 'gnu)
(eldev-use-package-archive 'melpa-unstable)
;; allow to load test helpers
(eldev-add-loading-roots 'test "test/utils")
;; Tell checkdoc not to demand two spaces after a period.
(setq sentence-end-double-space nil)
(setf eldev-lint-default '(elisp))
(setf eldev-standard-excludes `(:or ,eldev-standard-excludes "org-roam-macs.el"))
(with-eval-after-load 'elisp-lint
;; We will byte-compile with Eldev.
(setf elisp-lint-ignored-validators '("package-lint" "fill-column")
enable-local-variables :all))
;; Teach linter how to properly indent emacsql vectors
(eldev-add-extra-dependencies 'lint 'emacsql)
(add-hook 'eldev-lint-hook
(lambda ()
(eldev-load-project-dependencies 'lint nil t)
(require 'emacsql)
(call-interactively #'emacsql-fix-vector-indentation)))

69
Makefile
View File

@ -1,56 +1,29 @@
# * makem.sh/Makefile --- Script to aid building and testing Emacs Lisp packages
.PHONY: clean
clean:
eldev clean all
# This Makefile is from the makem.sh repo: <https://github.com/alphapapa/makem.sh>.
.PHONY: prepare
prepare:
eldev -C --unstable -p -dtT prepare
# * Arguments
.PHONY: lint
lint:
eldev -C --unstable -T lint
# For consistency, we use only var=val options, not hyphen-prefixed options.
.PHONY: test
test:
eldev -C --unstable -T test
# NOTE: I don't like duplicating the arguments here and in makem.sh,
# but I haven't been able to find a way to pass arguments which
# conflict with Make's own arguments through Make to the script.
# Using -- doesn't seem to do it.
docs:
make -C doc all
ifdef install-deps
INSTALL_DEPS = "--install-deps"
endif
ifdef install-linters
INSTALL_LINTERS = "--install-linters"
endif
html:
make -C doc html-dir
ifdef sandbox
ifeq ($(sandbox), t)
SANDBOX = --sandbox
else
SANDBOX = --sandbox $(sandbox)
endif
endif
install: install-docs
ifdef debug
DEBUG = "--debug"
endif
install-docs: docs
make -C doc install-docs
# ** Verbosity
# Since the "-v" in "make -v" gets intercepted by Make itself, we have
# to use a variable.
verbose = $(v)
ifneq (,$(findstring vv,$(verbose)))
VERBOSE = "-vv"
else ifneq (,$(findstring v,$(verbose)))
VERBOSE = "-v"
endif
# * Rules
# TODO: Handle cases in which "test" or "tests" are called and a
# directory by that name exists, which can confuse Make.
%:
@./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS) $(@)
.DEFAULT: init
init:
@./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS)
install-info: info
make -C doc install-info

272
README.md
View File

@ -1,72 +1,232 @@
[![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)
[![Documentation Status](https://readthedocs.org/projects/org-roam/badge/?version=latest)](https://org-roam.readthedocs.io/en/latest/?badge=latest)
[![GitHub Release](https://img.shields.io/github/v/release/jethrokuan/org-roam)](https://img.shields.io/github/v/release/jethrokuan/org-roam)
# Org-roam [![GitHub Release][release-badge]][release] [![MELPA][melpa-badge]][melpa] [![License GPL 3][gpl3-badge]][gpl3]
## Synopsis
<img src="https://www.orgroam.com/img/logo.svg" align="right" alt="Org-roam Logo" width="240">
Org-roam is a rudimentary [Roam][roamresearch] replica built around
the all-powerful [Org-mode][org].
Like Roam, Org-roam offers a powerful and effortless non-hierarchical
note-taking approach. With Org-roam, notes flow naturally, making
note-taking fun and easy. Org-roam *enables* a note-taking workflow that
is not fluid with vanilla Org-mode (more in [this blog
post](https://blog.jethro.dev/posts/how_to_take_smart_notes_org/)).
The goal of the project is to implement core features of Roam around
Org-mode, and eventually introduce features enabled by the Emacs
Org-roam is a plain-text knowledge management system. It brings some of
[Roam's][roamresearch] more powerful features into the [Org-mode][org]
ecosystem.
Visit [the documentation
page](https://org-roam.readthedocs.io/en/latest/) for a tutorial and
more links.
Org-roam borrows principles from the Zettelkasten method, providing a solution
for non-hierarchical note-taking. It should also work as a plug-and-play
solution for anyone already using Org-mode for their personal wiki.
As of February 2020, it is in a very early stage of development.
- **Private and Secure**: Edit your personal wiki completely offline, entirely
in your control. Encrypt your notes with GPG. Take lasting notes in
plain-text.
- **Networked Thought**: Connect notes and thoughts together with ease using
backlinks. Discover surprising and previously unseen connections in your notes
with the built-in graph visualization.
- **Extensible and Powerful**: Leverage Emacs' fantastic text-editing interface,
and the mature Emacs and Org-mode ecosystem of packages.
- **Free and Open Source**: Org-roam is licensed under the GNU General Public
License version 3 or later.
## A Preview
<p align="center">
<img src="https://www.orgroam.com/img/screenshot.png" alt="Org-roam Screenshot" width="738">
</p>
Here's a screenshot of `org-roam`. The `org-roam` buffer shows
backlinks for the active org buffer in the left window, as well as the
surrounding content in the backlink file. The backlink database is
built asynchronously in the background, and is not noticeable to the
end user. The graph is generated from the link structure, and can be
used to navigate to the respective files.
![img](doc/images/org-roam-graph.gif)
- **[Documentation][docs]**
- **[Discourse][discourse]**
- **[Slack][slack]**
- **[Frequently Asked Questions][faq]**
- **[Changelog](CHANGELOG.md)**
## Installation
The recommended method is using use-package and straight, or a similar package manager.
Down below you will find basic installation instructions for how to quickly
install `org-roam` using various environments for various purposes. For more
detailed information, please read the [manual][docs].
### Using `package.el`
<details>
<summary>Toggle instuctions</summary>
You can install `org-roam` from [MELPA](https://melpa.org/) or [MELPA
Stable](https://stable.melpa.org/) using `package.el`:
```
M-x package-install RET org-roam RET
```
Here's a very basic sample for configuration of `org-roam` using `use-package`:
```emacs-lisp
(use-package org-roam
:after org
:hook
(after-init . org-roam-mode)
:straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
:ensure t
:custom
(org-roam-directory "/path/to/org-files/")
:bind (:map org-roam-mode-map
(("C-c n l" . org-roam)
("C-c n f" . org-roam-find-file)
("C-c n g" . org-roam-show-graph))
:map org-mode-map
(("C-c n i" . org-roam-insert))))
(org-roam-directory (file-truename "/path/to/org-files/"))
:bind (("C-c n l" . org-roam-buffer-toggle)
("C-c n f" . org-roam-node-find)
("C-c n g" . org-roam-graph)
("C-c n i" . org-roam-node-insert)
("C-c n c" . org-roam-capture)
;; Dailies
("C-c n j" . org-roam-dailies-capture-today))
:config
(org-roam-db-autosync-mode)
;; If using org-roam-protocol
(require 'org-roam-protocol))
```
For more detailed installation instructions (including instructions for
Spacemacs users), please see [the installation
documentation](https://org-roam.readthedocs.io/en/develop/installation/).
Note that the `file-truename` function is only necessary when you use symbolic
link to `org-roam-directory`. Org-roam won't automatically resolve symbolic link
to the directory.
</details>
## Knowledge Bases using Org-Roam
### Using `straight.el`
<details>
<summary>Toggle instuctions</summary>
Installation from MELPA or MELPA Stable using `straight.el`:
```emacs-lisp
(straight-use-package 'org-roam)
```
Or with `use-package`:
```emacs-lisp
(use-package org-roam
:straight t
...)
```
If you need to install the package directly from the source repository, instead
of from MELPA, the next sample shows how to do so:
```emacs-lisp
(use-package org-roam
:straight (:host github :repo "org-roam/org-roam"
:files (:defaults "extensions/*"))
...)
```
If you plan to use your own local fork for the development and contribution, the
next sample will get you there:
```emacs-lisp
(use-package org-roam
:straight (:local-repo "/path/to/org-roam-fork"
:files (:defaults "extensions/*")
:build (:not compile))
...)
```
</details>
### Using Doom Emacs
<details>
<summary>Toggle instuctions</summary>
Doom's `:lang org` module comes with support for `org-roam`, but it's not
enabled by default. To activate it pass `+roam2` flag to `org` module in your
`$DOOMDIR/init.el` (e.g. `(org +roam2)`), save the file and run `doom sync -u`
in your shell.
To provide better stability, Doom pins the package to a specific commit. If you
need to unpin it *(not recommended doing that, request Doom to bump the package
instead)* use the next in your `packages.el`:
```emacs-lisp
(unpin! org-roam)
```
If for some reasons you want to use a different recipe for `org-roam`, you can
use the next form in your `packages.el` to install the package from a recipe
repository (e.g. MELPA):
```emacs-lisp
(package! org-roam)
```
You can pass `:pin "commit hash"` to pin the package to a specific commit.
With the next sample you can install the package directly from the source
repository:
```emacs-lisp
(package! org-roam
:recipe (:host github :repo "org-roam/org-roam"
:files (:defaults "extensions/*")))
```
And if you plan to use your own local fork for the development or contribution,
the next sample will get you there:
```emacs-lisp
(package! org-roam
:recipe (:local-repo "/path/to/org-roam-fork"
:files (:defaults "extensions/*")
:build (:not compile)))
```
</details>
### Without a package manager
<details>
<summary>Toggle instructions</summary>
To install the package without using a package manager you have the next two
options:
1. Install the package by cloning it with `git` from the source repository.
2. Or install the package by downloading the latest [release
version](https://github.com/org-roam/org-roam/releases).
In both of the cases you will need to ensure that you have all the required
dependencies. These include:
- dash
- f
- s
- org (9.4 is the minimal required version!)
- emacsql
- emacsql-sqlite
- magit-section
- filenotify-recursive
After installing the package, you will need to properly setup `load-path` to the
package:
``` emacs-lisp
(add-to-list 'load-path "/path/to/org-roam/")
(add-to-list 'load-path "/path/to-org-roam/extensions/")
```
After which you should be able to resolve `(require 'org-roam)` call without any
problems.
Org-roam also comes with `.texi` files to integrate with Emacs' built-in Info
system. Read the manual to find more details for how to install them manually.
</details>
## Getting Started
[David Wilson](https://github.com/daviwil) of [System
Crafters](https://www.youtube.com/c/SystemCrafters) has produced an introductory
video that covers the basic commands:
[![Getting Started with Org Roam - Build a Second Brain in Emacs](https://img.youtube.com/vi/AyhPmypHDEw/0.jpg)](https://www.youtube.com/watch?v=AyhPmypHDEw)
## Getting Help
Before creating a new topic/issue, please be mindful of our time and ensure that
it has not already been addressed on [GitHub][issues] or on
[Discourse][discourse].
- If you are new to Emacs and have problem setting up Org-roam, please ask your
question on [Slack, channel #how-do-i][slack].
- For quick questions, please ask them on [Slack, channel
#troubleshooting][slack].
- If something is not working as it should, or if you would like to suggest a
new feature, please [create a new issue][issues].
- If you have questions about your workflow with the slip-box method, please
find a relevant topic on [Discourse][discourse], or create a new one.
## Knowledge Bases using Org-roam
- [Jethro Kuan](https://braindump.jethro.dev/)
([Source](https://github.com/jethrokuan/braindump/tree/master/org))
## Changelog
A changelog is being maintained [here](CHANGELOG.md)
- [Alexey Shmalko](https://braindump.rasen.dev/)
- [Sidharth Arya](https://sidhartharya.github.io/braindump/index.html)
## Contributing
@ -77,8 +237,18 @@ request. Please also see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
## License
Copyright © Jethro Kuan and contributors. Distributed under the GNU
General Public License, Version 3
General Public License, Version 3.
[roamresearch]: https://www.roamresearch.com/
[org]: https://orgmode.org/
[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg
[gpl3-badge]: https://img.shields.io/badge/license-GPL_3-green.svg
[gpl3]: http://www.gnu.org/licenses/gpl-3.0.txt
[melpa-badge]: https://melpa.org/packages/org-roam-badge.svg
[melpa]: https://melpa.org/#/org-roam
[release-badge]: https://img.shields.io/github/v/release/org-roam/org-roam
[release]: https://github.com/org-roam/org-roam/releases
[docs]: https://www.orgroam.com/manual.html
[discourse]: https://org-roam.discourse.group/
[slack]: https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg
[issues]: https://github.com/org-roam/org-roam/issues
[faq]: https://www.orgroam.com/manual.html#FAQ

107
default.mk Normal file
View File

@ -0,0 +1,107 @@
TOP := $(dir $(lastword $(MAKEFILE_LIST)))
## User options ######################################################
#
# You can override these settings in "config.mk" or on the command
# line.
#
# You might also want to set LOAD_PATH. If you do, then it must
# contain "-L .".
#
# If you don't do so, then the default is set in the "Load-Path"
# section below. The default assumes that all dependencies are
# installed either at "../<DEPENDENCY>", or when using package.el
# at "ELPA_DIR/<DEPENDENCY>-<HIGHEST-VERSION>".
sharedir ?= $(HOME)/.local/share
lispdir ?= $(sharedir)/emacs/site-lisp/org-roam
infodir ?= $(sharedir)/info
docdir ?= $(sharedir)/doc/org-roam
statsdir ?= $(TOP)/doc/stats
CP ?= install -p -m 644
MKDIR ?= install -p -m 755 -d
RMDIR ?= rm -rf
TAR ?= tar
SED ?= sed
EMACSBIN ?= emacs
BATCH = $(EMACSBIN) -Q --batch $(LOAD_PATH)
INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info)
MAKEINFO ?= makeinfo
MANUAL_HTML_ARGS ?= --css-ref /assets/page.css
## Files #############################################################
PKG = org-roam
PACKAGES = org-roam
TEXIPAGES = $(addsuffix .texi,$(PACKAGES))
INFOPAGES = $(addsuffix .info,$(PACKAGES))
HTMLFILES = $(addsuffix .html,$(PACKAGES))
HTMLDIRS = $(PACKAGES)
PDFFILES = $(addsuffix .pdf,$(PACKAGES))
EPUBFILES = $(addsuffix .epub,$(PACKAGES))
ELS = org-roam.el
ELS += org-roam-capture.el
ELS += org-roam-compat.el
ELS += org-roam-db.el
ELS += org-roam-mode.el
ELS += org-roam-node.el
ELS += org-roam-utils.el
ELS += extensions/org-roam-dailies.el
ELS += extensions/org-roam-graph.el
ELS += extensions/org-roam-overlay.el
ELS += extensions/org-roam-protocol.el
ELCS = $(ELS:.el=.elc)
ELMS = org-roam.el $(filter-out $(addsuffix .el,$(PACKAGES)),$(ELS))
ELGS = org-roam-autoloads.el org-roam-version.el
## Versions ##########################################################
VERSION ?= $(shell test -e $(TOP).git && git describe --tags --abbrev=0 | cut -c2-)
EMACS_VERSION = 26.1
EMACSOLD := $(shell $(BATCH) --eval \
"(and (version< emacs-version \"$(EMACS_VERSION)\") (princ \"true\"))")
ifeq "$(EMACSOLD)" "true"
$(error At least version $(EMACS_VERSION) of Emacs is required)
endif
## Load-Path #########################################################
ifndef LOAD_PATH
ELPA_DIR ?= $(HOME)/.emacs.d/elpa
SYSTYPE := $(shell $(EMACSBIN) -Q --batch --eval "(princ system-type)")
ifeq ($(SYSTYPE), windows-nt)
CYGPATH := $(shell cygpath --version 2>/dev/null)
endif
LOAD_PATH = -L $(TOP)
# When making changes here, then don't forget to adjust "Makefile",
# ".travis.yml", ".github/ISSUE_TEMPLATE/bug_report.md",
# `magit-emacs-Q-command' and the "Installing from the Git Repository"
# info node accordingly. Also don't forget to "rgrep \b<pkg>\b".
endif # ifndef LOAD_PATH
ifndef ORG_LOAD_PATH
ORG_LOAD_PATH = $(LOAD_PATH)
ORG_LOAD_PATH += -L $(TOP)../ox-texinfo-plus
ORG_LOAD_PATH += -L $(TOP)../org-mode/contrib/lisp
ORG_LOAD_PATH += -L $(TOP)../org-mode/lisp
endif
## Publish ###########################################################
PUBLISH_TARGETS ?= html html-dir pdf epub
DOCBOOK_XSL ?= /usr/share/xml/docbook/stylesheet/docbook-xsl/epub/docbook.xsl
EPUBTRASH = epub.xml META-INF OEBPS

0
doc/.nojekyll Normal file
View File

37
doc/AUTHORS.md Normal file
View File

@ -0,0 +1,37 @@
Authors
=======
The following people have contributed to Org-Roam.
Names below are sorted alphabetically.
Author
------
- Jethro Kuan <jethrokuan95@gmail.com>
Maintainers
----------
- Jethro Kuan <jethrokuan95@gmail.com>
- Leo Vivier <leo.vivier+dev@gmail.com>
Contributors
------------
- Alexey Shmalko <rasen.dubi@gmail.com>
- James Ravn <james@r-vn.org>
- Jethro Kuan <jethrokuan95@gmail.com>
- Johann Klähn <johann@jklaehn.de>
- Josh English <josh@joshenglish.com>
- Jürgen Hötzel <juergen@archlinux.org>
- Langston Barrett <langston.barrett@gmail.com>
- Leo Vivier <leo.vivier+dev@gmail.com>
- Michael Glaesemann <grzm@seespotcode.net>
- Michael Herold <github@michaeljherold.com>
- Noboru <noboru.ota@gmail.com>
- N V <44036031+progfolio@users.noreply.github.com>
- Rafael Accácio Nogueira <raccacio@poli.ufrj.br>
- Roland Coeurjoly <rolandcoeurjoly@gmail.com>
- Sayan <dit7ya@users.noreply.github.com>
- Tim Quelch <tim@tquelch.com>

127
doc/Makefile Normal file
View File

@ -0,0 +1,127 @@
-include ../config.mk
include ../default.mk
###################################################################
MANUAL_HTML_ARGS = --css-ref assets/page.css
.PHONY: texi install clean AUTHORS.md stats
all: info
## Build #############################################################
info: $(INFOPAGES) dir
html: $(HTMLFILES)
pdf: $(PDFFILES)
epub: $(EPUBFILES)
%.info: %.texi
@printf "Generating $@\n"
@$(MAKEINFO) --no-split $< -o $@
dir: org-roam.info
@printf "Generating dir\n"
@echo $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@
%.html: %.texi
@printf "Generating $@\n"
@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $<
html-dir:
@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) org-roam.texi
mv org-roam.html manual.html
%.pdf: %.texi
@printf "Generating $@\n"
@texi2pdf --clean $< > /dev/null
%.epub: %.texi
@printf "Generating $@\n"
@$(MAKEINFO) --docbook $< -o epub.xml
@xsltproc $(DOCBOOK_XSL) epub.xml 2> /dev/null
@echo "application/epub+zip" > mimetype
@zip -X --quiet --recurse-paths -0 $@ mimetype
@zip -X --quiet --recurse-paths -9 --no-dir-entries $@ META-INF OEBPS
@$(RMDIR) $(EPUBTRASH)
## Install ###########################################################
install: install-info install-docs
install-docs: install-info
@$(MKDIR) $(DESTDIR)$(docdir)
$(CP) AUTHORS.md $(DESTDIR)$(docdir)
install-info: info
@$(MKDIR) $(DESTDIR)$(infodir)
$(CP) $(INFOPAGES) $(DESTDIR)$(infodir)
## Clean #############################################################
clean:
@printf "Cleaning doc/*...\n"
@$(RMDIR) dir $(INFOPAGES) $(HTMLFILES) $(HTMLDIRS) $(PDFFILES)
@$(RMDIR) $(EPUBFILES) $(EPUBTRASH)
## Release management ################################################
ORG_ARGS = --batch -Q $(ORG_LOAD_PATH)
ORG_ARGS += -l ox-extra -l ox-texinfo+
ORG_ARGS += --eval "(or (require 'org-man nil t) (require 'ol-man))"
ORG_EVAL = --eval "(ox-extras-activate '(ignore-headlines))"
ORG_EVAL += --eval "(setq indent-tabs-mode nil)"
ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)"
ORG_EVAL += --funcall org-texinfo-export-to-texinfo
# This target first bumps version strings in the Org source. The
# necessary tools might be missing so other targets do not depend
# on this target and it has to be run explicitly when appropriate.
#
# AMEND=t make texi Update manual to be amended to HEAD.
# VERSION=N make texi Update manual for release.
#
texi:
@$(EMACSBIN) $(ORG_ARGS) $(PKG).org $(ORG_EVAL)
@printf "\n" >> $(PKG).texi
@rm -f $(PKG).texi~
stats:
@printf "Generating statistics\n"
@gitstats -c style=/assets/stats.css -c max_authors=999 $(TOP) $(statsdir)
authors: AUTHORS.md
AUTHORS.md:
@printf "Generating AUTHORS.md..."
@test -e $(TOP).git \
&& (printf "$$AUTHORS_HEADER\n" > $@ \
&& git log --pretty=format:'- %aN <%aE>' | sort -u >> $@ \
&& printf "done\n" ; ) \
|| printf "FAILED (non-fatal)\n"
# Templates ##########################################################
define AUTHORS_HEADER
Authors
=======
The following people have contributed to Org-Roam.
Names below are sorted alphabetically.
Author
------
- Jethro Kuan <jethrokuan95@gmail.com>
Maintainers
----------
- Jethro Kuan <jethrokuan95@gmail.com>
- Leo Vivier <leo.vivier+dev@gmail.com>
Contributors
------------
endef
export AUTHORS_HEADER

68
doc/assets/page.css Normal file
View File

@ -0,0 +1,68 @@
:root {
--border: #526980;
--code: #007;
}
body {
margin: 5ex 10ex;
max-width: 80ex;
line-height: 1.5;
font-family: sans-serif;
}
h1, h2, h3 {
font-weight: normal;
}
pre, code {
font-family: x, monospace;
}
pre {
padding: 1ex;
background: #eee;
border: solid 1px #ddd;
min-width: 0;
font-size: 80%;
overflow: auto;
}
code {
color: var(--code);
}
img {
max-width: 100%;
}
table {
border-collapse: collapse;
width: 100%;
}
pre.menu-comment {
background: none;
border: none;
font-family: sans-serif;
padding: 0;
margin: 0;
font-size: 100%;
}
thead {
border-bottom: 1px solid var(--border);
}
tfoot {
border-top: 1px solid var(--border);
}
blockquote {
margin-left: 1rem;
font-style: italic;
font-family: serif;
border-left: 3px solid;
border-left-color: currentcolor;
border-color: var(--text-color);
padding-left: 1em;
}

11
doc/comparison.md
View File

@ -1,11 +0,0 @@
---
title: "Comparing Org-Roam With Other Packages"
metaTitle: "Comparing Org-Roam With Other Packages"
metaDescription: "Comparing Org-Roam With Other Packages"
---
# Org-brain
# Zetteldeft
# Org-zettelkasten

121
doc/configuration.md
View File

@ -1,121 +0,0 @@
To ensure that Org-roam remains manageable, the number of
configuration options is deliberately kept small. However, we have
attempted to accommodate as many usage styles as possible.
In this section, we'll go over the main customization options
available to Org-Roam. This section is *crucial*. We need to exploit
the flexibility of Emacs, and mould our tools exactly to our liking.
All of Org-roam's customization options can be viewed via `M-x
customize-group org-roam`.
## Setting the Org-roam Directory
Perhaps the single most important variable to set is
`org-roam-directory`. Set `org-roam-directory` to the folder
containing all your Org files:
```emacs-lisp
(setq org-roam-directory "/path/to/org/")
```
Every Org file, at any level of nesting, within `/path/to/org/` is
considered part of the Org-roam ecosystem.
## Org-roam Buffer
The Org-roam buffer defaults to popping up from the right. You may
choose to set it to pop up from the left with `(setq
org-roam-buffer-position 'left)`.
The Org-roam buffer name can also be renamed: e.g. `(setq
org-roam-buffer "*my-buffer-name*")`.
The Org-roam buffer width is adjustable via `org-roam-buffer-width`.
The value of `org-roam-buffer-width` set as a percentage of the total
frame width. For example:
```emacs-lisp
(setq org-roam-buffer-width 0.4)
```
Will result in the Org-roam buffer taking up 40% of the screen width.
I have found this to be a good number.
## Org-roam Links
By default, links are inserted with the title as the link description.
This can make them hard to distinguish from external links. If you
wish, you may choose add special indicators for Org-roam links by
tweaking `org-roam-link-title-format`, for example:
```emacs-lisp
(setq org-roam-link-title-format "R:%s")
```
## Org-roam Files
These customization options revolve around the Org files created and
managed by Org-roam.
### Automatically Creating Files Using Timestamp
A common hassle is ensuring that files are uniquely named within the
Org-roam directory. Org-roam's default workflow utilizes the title of
Org files in all of its main commands (`org-roam-insert`,
`org-roam-find-file`). Hence, having any unique file name is a decent
option, and the default workflow uses the timestamp as the filename.
The format of the filename is controlled by the function
`org-roam-file-name-function`, which defaults to a format like
`YYYYMMDDHHMMSS_title_here.org`. You may choose to define your own
function to change this.
If you wish to be prompted to change the file name on creation, set
`org-roam-filename-noconfirm` to `nil`:
```emacs-lisp
(setq org-roam-filename-noconfirm nil)
```
It is then the user's responsibility to ensure that the file names are
unique.
### Autopopulating Titles
The default workflow uses the title of the Org file in several
commands. The title is specified via the `#+TITLE:` attribute,
typically near the top of the file. The option
`org-roam-autopopulate-title` defaults to `t`. When true, the title
attribute is automatically inserted into the files created via
Org-roam commands. Setting it to `nil` will disable this behaviour.
### Encryption
Encryption (via GPG) can be enabled for all new files by setting
`org-roam-encrypt-files` to `t`. When enabled, new files are created
with the .org.gpg extension and decryption are handled automatically
by EasyPG. Note that this causes Emacs to ask for password when the
cache is built (if you have an encrypted file in `org-roam-directory`)
as well as each time a new file is created. It might be a good idea to
cache the password in order to make this more managable.
## Org-roam Graph Viewer
Org-roam generates an SVG image using
[Graphviz](https://graphviz.org/). To setup graph navigation, see the
[Graph Setup](graph_setup.md) page.
Org-roam tries its best to locate the Graphviz executable from your
PATH, but if it fails to do so, you may set it manually:
```
(setq org-roam-graphviz-executable "/path/to/dot")
```
Org-roam also attempts to use Firefox (located on PATH) to view the
SVG, you may choose to set it to any compatible program:
```
(setq org-roam-graph-viewer "/path/to/image-viewer")
```

85
doc/css/styles.css Normal file
View File

@ -0,0 +1,85 @@
body {
margin: 20px;
background: #303030;
color: #f5f5f5;
font-size: 1.6rem;
font-weight: 300;
}
.container {
max-width: 800px;
}
.nav {
margin-top: 5rem;
}
.nav-item a {
/* color: #797979; */
color: #bebebe;
text-decoration: none;
font-family: "Consolas", "Monaco", "Menlo", monospace;
}
.nav-item a:hover {
cursor: pointer;
/* color: #4d4a4a; */
color: #dcdcdc;
border: none;
}
.hero {
color: #f5f5f5;
}
.hero div {
margin-bottom: 5rem;
}
.hero h3 {
/* font-family: "Edelsans", sans-serif; */
font-size: 5rem;
margin-bottom: 0;
}
.hero h5 {
margin-top: 1rem;
margin-bottom: 0;
/* font-weight: 200; */
font-weight: 250;
}
.grid-demo-col {
background: #e4e4e4;
}
a {
color: #cd86ff;
}
a:hover {
color: #dbb9f3;
}
img {
max-width: 100%;
}
.footer-links {
font-size: 1.5rem;
color: #f5f5f5;
text-decoration: none;
font-weight: 250;
}
.header {
font-weight: 200;
}
#footer {
margin-bottom: 3rem;
}
#footer h5 {
margin-bottom: 1.5rem;
}

126
doc/ecosystem.md
View File

@ -1,126 +0,0 @@
A number of packages work well combined with Org-Roam:
## Deft
[Deft][deft] provides a nice interface for browsing and filtering
org-roam notes.
```emacs-lisp
(use-package deft
:after org
:bind
("C-c n d" . deft)
:custom
(deft-recursive t)
(deft-use-filter-string-for-filename t)
(deft-default-extension "org")
(deft-directory "/path/to/org-roam-files/"))
```
If the title of the Org file is not the first line, you might not get
nice titles. You may choose to patch this to use `org-roam`'s
functionality. Here I'm using [el-patch](https://github.com/raxod502/el-patch):
```emacs-lisp
(use-package el-patch
:straight (:host github
:repo "raxod502/el-patch"
:branch "develop"))
(eval-when-compile
(require 'el-patch))
(use-package deft
;; same as above...
:config/el-patch
(defun deft-parse-title (file contents)
"Parse the given FILE and CONTENTS and determine the title.
If `deft-use-filename-as-title' is nil, the title is taken to
be the first non-empty line of the FILE. Else the base name of the FILE is
used as title."
(el-patch-swap (if deft-use-filename-as-title
(deft-base-filename file)
(let ((begin (string-match "^.+$" contents)))
(if begin
(funcall deft-parse-title-function
(substring contents begin (match-end 0))))))
(org-roam--get-title-or-slug file))))
```
The Deft interface can slow down quickly when the number of files get
huge. [Notdeft][notdeft] is a fork of Deft that uses an external
search engine and indexer.
## Org-journal
[Org-journal](https://github.com/bastibe/org-journal) is a more
powerful alternative to the simple function `org-roam-today`. It
provides better journaling capabilities, and a nice calendar interface
to see all dated entries.
```emacs-lisp
(use-package org-journal
:bind
("C-c n j" . org-journal-new-entry)
:custom
(org-journal-date-prefix "#+TITLE: ")
(org-journal-file-format "%Y-%m-%d.org")
(org-journal-dir "/path/to/org-roam-files/")
(org-journal-date-format "%A, %d %B %Y"))
```
## Note-taking Add-ons
These are some plugins that make note-taking in Org-mode more
enjoyable.
### Org-download
[Org-download][org-download] lets you screenshot and yank images from
the web into your notes:
![org-download](images/org-download.gif)
```emacs-lisp
(use-package org-download
:after org
:bind
(:map org-mode-map
(("s-Y" . org-download-screenshot)
("s-y" . org-download-yank))))
```
### mathpix.el
[mathpix.el][mathpix-el] uses [Mathpix's](https://mathpix.com/) API to convert clips into
latex equations:
![mathpix](images/mathpix.gif)
```emacs-lisp
(use-package mathpix.el
:straight (:host github :repo "jethrokuan/mathpix.el")
:custom ((mathpix-app-id "app-id")
(mathpix-app-key "app-key"))
:bind
("C-x m" . mathpix-screenshot))
```
### Org-noter / Interleave
[Org-noter][org-noter] and [Interleave][interleave] are both projects
that allow synchronised annotation of documents (PDF, EPUB etc.)
within Org-mode.
### Org-ref
[Org-ref][org-ref] does citation and bibliography management in
Org-mode, and a great tool for scientific notes.
[deft]: https://jblevins.org/projects/deft/
[notdeft]: https://github.com/hasu/notdeft
[org-download]: https://github.com/abo-abo/org-download
[mathpix-el]: https://github.com/jethrokuan/mathpix.el
[org-noter]: https://github.com/weirdNox/org-noter
[interleave]: https://github.com/rudolfochrist/interleave
[org-ref]: https://github.com/jkitchin/org-ref

78
doc/graph_setup.md
View File

@ -1,78 +0,0 @@
The setup is similar to that of org-protocol. Here `roam://` links are
defined, and need to be associated with an application.
The gist of the setup is setting up a Bash script to trim off the
`roam://` prefix from the link, causing the desktop application to
call `emacsclient path/to/org-roam-file.org`.
## Linux
Create a desktop application. I place mine in
`~/.local/share/applications/roam.desktop`:
```
[Desktop Entry]
Name=Org-Roam Client
Exec=/home/jethro/.local/bin/launch_emacs %u
Icon=emacs-icon
Type=Application
Terminal=false
MimeType=x-scheme-handler/roam
```
Note the `Exec` key is set to a bash script poorly named
`launch_emacs`. You can set it to whatever you want.
Create the corresponding bash script, and make it executable. Here's
how it looks like:
```bash
#!/usr/bin/env bash
emacsclient "${1#*:}"
```
Finally, associate `roam://` links with the desktop application by
running in your shell:
```bash
xdg-mime default roam.desktop x-scheme-handler/roam
```
## Mac OS
One solution to this, recommended in [Issue
#115](https://github.com/jethrokuan/org-roam/issues/115), is to use
[Platypus](https://github.com/sveinbjornt/Platypus). Here are the
instructions for setting up with Platypus and Chrome:
1. Create an executable `launch-emacs.sh` script:
```sh
#!/usr/bin/env bash
/usr/local/bin/emacsclient --no-wait "${1#*:}"
```
2. Install and launch Platypus (with [Homebrew](https://brew.sh/)):
```sh
brew cask install playtpus
```
3. Playtpus settings:
- App Name: `OrgRoam`
- Script Type: `env` and `/usr/bin/env`
- Script Path: `/path/to/your/launch-emacs.sh`
- Tick Accept dropped items and click Settings
- Tick Accept dropped files
- Tick Register as URI scheme handler
- Add `roam` as a protocol
- Create the app
To disable the "confirm" prompt in Chrome, you can also make Chrome
show a checkbox to tick, so that the `OrgRoam` app will be used
without confirmation. To do this, run in a shell:
```sh
defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
```

15
doc/htmlxref.cnf Normal file
View File

@ -0,0 +1,15 @@
# https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html
EMACS = https://www.gnu.org/software/emacs/manual
auth mono ${EMACS}/html_mono/auth.html
auth node ${EMACS}/html_node/auth/
ediff mono ${EMACS}/html_mono/ediff.html
ediff node ${EMACS}/html_node/ediff/
elisp mono ${EMACS}/html_mono/elisp.html
elisp node ${EMACS}/html_node/elisp/
emacs mono ${EMACS}/html_mono/emacs.html
emacs node ${EMACS}/html_node/emacs/

BIN
doc/images/org-ref-citelink.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 279 KiB

BIN
doc/images/org-roam-bibtex.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

BIN
doc/images/roam-ref.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.5 MiB

BIN
doc/img/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 85 KiB

572
doc/img/logo.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
doc/img/screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 272 KiB

168
doc/index.html Normal file
View File

@ -0,0 +1,168 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="An Effortless PKM System." />
<meta name="author" content="Org-roam Contributors" />
<title>Org-roam</title>
<link rel="stylesheet" href="https://unpkg.com/wingcss" />
<link rel="stylesheet" type="text/css" href="./css/styles.css" />
<script src="https://code.iconify.design/1/1.0.6/iconify.min.js"></script>
</head>
<body>
<section class="hero container center text-center">
<div>
<img src="./img/logo.png" alt="Org-roam Logo" height="200" />
<h3>Org-roam</h3>
<h5>A plain-text personal knowledge management system.</h5>
</div>
</section>
<section class="container center">
<div>
<img src="./img/screenshot.png" alt="screenshot" />
</div>
</section>
<section id="features" class="container center">
<div>
<h3 class="header">FEATURES</h3>
<div class="row">
<div class="col">
<h5 class="left">
<iconify-icon data-icon="fxemoji:lock"></iconify-icon> &nbsp;
Private and Secure
</h5>
<p class="content">
Edit your personal wiki completely offline, entirely in your
control. Encrypt your notes with GPG. Take lasting notes in
plain-text.
</p>
</div>
<div class="col">
<h5 class="left">
<iconify-icon data-icon="flat-color-icons:link"></iconify-icon>
&nbsp; Make Connections
</h5>
<p class="content">
Connect notes and thoughts together with ease using backlinks.
Discover surprising and previously unseen connections in your
notes with the built-in graph visualization.
</p>
</div>
</div>
<div class="row">
<div class="col">
<h5 class="left">
<iconify-icon data-icon="twemoji:puzzle-piece"></iconify-icon>
&nbsp; Extensible and Powerful
</h5>
<p class="content">
Leverage Emacs' fantastic text-editing interface, and the mature
Emacs and Org-mode ecosystem of packages.
</p>
</div>
<div class="col">
<h5 class="left">
<iconify-icon data-icon="logos:git-icon"></iconify-icon> &nbsp;
Free and Open Source
</h5>
<p class="content">
Org-roam is licensed under the GNU General Public License version
3 or later. You are free to extend its functionality and
contribute back. Find
us <a href="https://github.com/org-roam/org-roam">here</a>.
</p>
</div>
</div>
</div>
</section>
<section id="links" class="container">
<div>
<h3 class="header">LINKS</h3> New to Emacs and Org-mode, and trying to
find your way around? Org-roam has an inclusive community of users
passionate about Personal Knowledge Management -- we're happy to help!
You can find us on Discourse and Slack.
<ul>
<li>Read our documentation within Emacs, or on the <a href="https://www.orgroam.com/manual.html">Online Manual</a></li>
<li>Participate in our forum discussions on <a href="https://org-roam.discourse.group">Discourse</a></li>
<li>Chat with us on <a href="https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg">Slack</a></li>
</ul>
</div>
</section>
<section id="footer" class="row container">
<div class="col">
<div class="row">
<h5 class="header">Ecosystem</h5>
</div>
<div class="row">
<a
class="content footer-links"
href="https://github.com/org-roam/org-roam-bibtex"
>org-roam-bibtex</a
>
</div>
<div class="row">
<a
class="content footer-links"
href="https://github.com/org-roam/org-roam-ui"
>org-roam-ui</a
>
</div>
</div>
<div class="col">
<div class="row">
<h5 class="header">Resources</h5>
</div>
<div class="row">
<a
class="content footer-links"
href="https://github.com/org-roam/org-roam/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc"
>Open Issues</a
>
</div>
<div class="row">
<a
class="content footer-links"
href="https://github.com/org-roam/org-roam/releases"
>Releases</a
>
</div>
</div>
<div class="col">
<div class="row">
<h5 class="header">Connect</h5>
</div>
<div class="row">
<a
class="content footer-links"
href="https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg"
>Slack</a
>
</div>
<div class="row">
<a
class="content footer-links"
href="https://org-roam.discourse.group/"
>Discourse</a
>
</div>
</div>
</section>
</body>
</html>

41
doc/index.md
View File

@ -1,41 +0,0 @@
![org-roam][org-roam-intro-image]
## What is Org-Roam?
Org-roam is a rudimentary [Roam][roamresearch] replica built around
the all-powerful [Org-mode][org].
Like Roam, Org-roam offers a powerful and effortless non-hierarchical
note-taking approach. With Org-roam, notes flow naturally, making
note-taking fun and easy. To understand more about Roam, I recommend
the following links:
- [Building a second brain in
Roam](https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might)
- [Roam: Why I Love It and How I Use
It](https://www.nateliason.com/blog/roam)
The goal of the project is to implement core features of Roam around
Org-mode, and eventually introduce features enabled by the Emacs
ecosystem.
## Why build Org-Roam?
With Org-roam, you:
1. Never have to leave Emacs.
2. Can leverage all the powerful features of Org-mode: LaTeX, tables,
and the whole to-do ecosystem (org-agenda etc.)
3. Be in full control your second brain, and access it offline. Never
share your data with anyone
There are several packages that are similar to Org-roam, see the
[Comparison](comparison.md) page for a detailed comparison.
## Project Status
As of February 2020, it is in a very early stage of development.
[org-roam-intro-image]: images/org-roam-intro.png
[roamresearch]: https://www.roamresearch.com/
[org]: https://orgmode.org/

93
doc/installation.md
View File

@ -1,93 +0,0 @@
## Installation
The recommended method is using [use-package][use-package] and
[straight][straight], or a similar package manager.
```
(use-package org-roam
:after org
:hook
(after-init . org-roam-mode)
:straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
:custom
(org-roam-directory "/path/to/org-files/")
:bind (:map org-roam-mode-map
(("C-c n l" . org-roam)
("C-c n f" . org-roam-find-file)
("C-c n g" . org-roam-show-graph))
:map org-mode-map
(("C-c n i" . org-roam-insert))))
```
If not using package.el, you can also clone it into your Emacs
directory and add it to your load path:
```
git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
```
```
(use-package org-roam
:after org
:load-path "elisp/"
:hook
(after-init . org-roam-mode)
:straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
:custom
(org-roam-directory "/path/to/org-files/")
:bind (:map org-roam-mode-map
(("C-c n l" . org-roam)
("C-c n f" . org-roam-find-file)
("C-c n g" . org-roam-show-graph))
:map org-mode-map
(("C-c n i" . org-roam-insert))))
```
Or without use-package:
```
(add-to-list 'load-path "./elisp")
(require 'org-roam)
```
There are a number of important configuration options, that greatly
affect the Roam workflow. Do look through them at the
[Configuration](configuration.md) page.
[use-package]: https://github.com/jwiegley/use-package
[straight]: https://github.com/raxod502/straight.el
## Spacemacs
If you are using Spacemacs, you can easily install org-roam by creating a simple layer that wraps org-roam. Paste the following into a new file `/.emacs.d/private/org-roam/packages.el`.
```
(defconst org-roam-packages
'((org-roam :location
(recipe :fetcher github :repo "jethrokuan/org-roam" :branch "develop"))))
(defun org-roam/init-org-roam ()
(use-package org-roam
:after org
:hook
(after-init . org-roam-mode)
:custom
(org-roam-directory "/path/to/org-files/")
:init
(progn
(spacemacs/declare-prefix "ar" "org-roam")
(spacemacs/set-leader-keys
"arl" 'org-roam
"art" 'org-roam-today
"arf" 'org-roam-find-file
"arg" 'org-roam-show-graph)
(spacemacs/declare-prefix-for-mode 'org-mode "mr" "org-roam")
(spacemacs/set-leader-keys-for-major-mode 'org-mode
"rl" 'org-roam
"rt" 'org-roam-today
"rb" 'org-roam-switch-to-buffer
"rf" 'org-roam-find-file
"ri" 'org-roam-insert
"rg" 'org-roam-show-graph))))
```
Next, append `org-roam` to the `dotspacemacs-configuration-layers` list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or restart Emacs to load `org-roam`. It's functions are available under the prefix `SPC a r` and `, r` when visiting an org-mode buffer.

20
doc/notetaking_workflow.md
View File

@ -1,20 +0,0 @@
## Recommended Books
- [How to Take Smart Notes][1]
## Articles
- [How to Take Smart Notes in Org-mode - Jethro Kuan][7]
- [The Zettelkasten Method - LessWrong 2.0][3]
- [Building a second brain in Roam][4]
- [Roam: Why I Love It and How I Use It][5]
- [Adam Keesling's Twitter Thread][6]
## What to Do With Your Notes
- [How to Use Roam to Outline a New Article in Under 20 Minutes][2]
[1]: https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes?ac=1&from_search=true&qid=6L8iEE1FIA&rank=1
[2]: https://www.youtube.com/watch?v=RvWic15iXjk
[3]: https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1
[4]: https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might
[5]: https://www.nateliason.com/blog/roam
[6]: https://twitter.com/adam_keesling/status/1196864424725774336?s=20
[7]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/

1537
doc/org-roam.org Normal file
View File

File diff suppressed because it is too large Load Diff

2121
doc/org-roam.texi Normal file
View File

File diff suppressed because it is too large Load Diff

2
doc/requirements.txt
View File

@ -1,2 +0,0 @@
mkdocs-material==4.6.2
pymdown-extensions==6.3

69
doc/tour.md
View File

@ -1,69 +0,0 @@
Org-roam was built to support a workflow that was not possible with
vanilla Org-mode. This flow is modelled after the [Zettelkasten
method][zettelkasten], and many of [Roam Research][roam]'s workflows.
Understanding this flow is crucial! Org-roam doesn't auto-magically
make your note-taking better -- it's changing the note-taking workflow
that does.
To understand more the methods and madness, the [Note-Taking
Workflow][appendix:ntw] page contains a page of useful references.
I've also written [a post][jethro-blog-post] about how I use Org-roam.
Without further ado, let's begin!
## Building the Cache
Assuming you've set `org-roam-directory` appropriately, running `M-x
org-roam--build-cache-async` should build up the caches that will
allow you to begin using Org-roam. I do this on startup:
```emacs-lisp
(add-hook 'after-init-hook 'org-roam--build-cache-async)
```
## Finding a Note
`org-roam-find-file` shows you the list of notes you currently have in
Org-roam. Selecting the title will bring you to the corresponding
note. Entering a title of a note that does not yet exist will create a
new note with that title.
![org-roam-find-file](images/org-roam-find-file.gif)
## Inserting Links
Within your Org-roam notes, you are encouraged to liberally insert
links to existing (or new) Org-roam notes with `org-roam-insert`.
Entering a non-existent title will also create a new note with that
title.
![org-roam-insert](images/org-roam-insert-filetag.gif)
It is crucial for good usage of Org-roam to insert links liberally,
where you want them the notes to resurface!
## The Org-roam Buffer
All of Org-roam's operations are designed such that the built cache is
a consistent view of the inter-connectivity between your notes. The
Org-roam buffer shows backlinks: i.e. the files that link to the
currently viewed file, along with some surrounding context. The
Org-roam buffer will always show the backlinks for the current
Org-roam file in view.
![org-roam-buffer](images/org-roam-buffer.gif)
## Exporting the Graph
It's also possible to export the links as a graph, using graphviz. The
generated graph is navigable in Emacs, but requires some additional
setup, which I describe in the [Graph Appendix][appendix:graph-setup]
page.
![org-roam-graph](images/org-roam-graph.gif)
[zettelkasten]: https://zettelkasten.de/
[appendix:ntw]: notetaking_workflow.md
[appendix:graph-setup]: graph_setup.md
[roam]: https://www.roamresearch.com/
[jethro-blog-post]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/

338
extensions/org-roam-dailies.el Normal file
View File

@ -0,0 +1,338 @@
;;; org-roam-dailies.el --- Daily-notes for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
;;;
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Copyright © 2020 Leo Vivier <leo.vivier+dev@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; Leo Vivier <leo.vivier+dev@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org-roam "2.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This extension provides functionality for creating daily-notes, or shortly
;; "dailies". Dailies implemented here as a unique node per unique file, where
;; each file named after certain date and stored in `org-roam-dailies-directory'.
;;
;; One can use dailies for various purposes, e.g. journaling, fleeting notes,
;; scratch notes and whatever else you can came up with.
;;
;;; Code:
(require 'f)
(require 'dash)
(require 'org-roam)
;;; Faces
(defface org-roam-dailies-calendar-note
'((t :inherit (org-link) :underline nil))
"Face for dates with a daily-note in the calendar."
:group 'org-roam-faces)
;;; Options
(defcustom org-roam-dailies-directory "daily/"
"Path to daily-notes.
This path is relative to `org-roam-directory'."
:group 'org-roam
:type 'string)
(defcustom org-roam-dailies-find-file-hook nil
"Hook that is run right after navigating to a daily-note."
:group 'org-roam
:type 'hook)
(defcustom org-roam-dailies-capture-templates
`(("d" "default" entry
"* %?"
:if-new (file+head "%<%Y-%m-%d>.org"
"#+title: %<%Y-%m-%d>\n")))
"Capture templates for daily-notes in Org-roam.
Note that for daily files to show up in the calendar, they have to be of format
\"org-time-string.org\".
See `org-roam-capture-templates' for the template documentation."
:group 'org-roam
:type '(repeat
(choice (list :tag "Multikey description"
(string :tag "Keys ")
(string :tag "Description"))
(list :tag "Template entry"
(string :tag "Keys ")
(string :tag "Description ")
(choice :tag "Capture Type " :value entry
(const :tag "Org entry" entry)
(const :tag "Plain list item" item)
(const :tag "Checkbox item" checkitem)
(const :tag "Plain text" plain)
(const :tag "Table line" table-line))
(choice :tag "Template "
(string)
(list :tag "File"
(const :format "" file)
(file :tag "Template file"))
(list :tag "Function"
(const :format "" function)
(function :tag "Template function")))
(plist :inline t
;; Give the most common options as checkboxes
:options (((const :format "%v " :if-new)
(choice :tag "Node location"
(list :tag "File"
(const :format "" file)
(string :tag " File"))
(list :tag "File & Head Content"
(const :format "" file+head)
(string :tag " File")
(string :tag " Head Content"))
(list :tag "File & Outline path"
(const :format "" file+olp)
(string :tag " File")
(list :tag "Outline path"
(repeat (string :tag "Headline"))))
(list :tag "File & Head Content & Outline path"
(const :format "" file+head+olp)
(string :tag " File")
(string :tag " Head Content")
(list :tag "Outline path"
(repeat (string :tag "Headline"))))))
((const :format "%v " :prepend) (const t))
((const :format "%v " :immediate-finish) (const t))
((const :format "%v " :jump-to-captured) (const t))
((const :format "%v " :empty-lines) (const 1))
((const :format "%v " :empty-lines-before) (const 1))
((const :format "%v " :empty-lines-after) (const 1))
((const :format "%v " :clock-in) (const t))
((const :format "%v " :clock-keep) (const t))
((const :format "%v " :clock-resume) (const t))
((const :format "%v " :time-prompt) (const t))
((const :format "%v " :tree-type) (const week))
((const :format "%v " :unnarrowed) (const t))
((const :format "%v " :table-line-pos) (string))
((const :format "%v " :kill-buffer) (const t))))))))
;;; Commands
;;;; Today
;;;###autoload
(defun org-roam-dailies-capture-today (&optional goto)
"Create an entry in the daily-note for today.
When GOTO is non-nil, go the note without creating an entry."
(interactive "P")
(org-roam-dailies--capture (current-time) goto))
;;;###autoload
(defun org-roam-dailies-goto-today ()
"Find the daily-note for today, creating it if necessary."
(interactive)
(org-roam-dailies-capture-today t))
;;;; Tomorrow
;;;###autoload
(defun org-roam-dailies-capture-tomorrow (n &optional goto)
"Create an entry in the daily-note for tomorrow.
With numeric argument N, use the daily-note N days in the future.
With a `C-u' prefix or when GOTO is non-nil, go the note without
creating an entry."
(interactive "p")
(org-roam-dailies--capture (time-add (* n 86400) (current-time)) goto))
;;;###autoload
(defun org-roam-dailies-goto-tomorrow (n)
"Find the daily-note for tomorrow, creating it if necessary.
With numeric argument N, use the daily-note N days in the
future."
(interactive "p")
(org-roam-dailies-capture-tomorrow n t))
;;;; Yesterday
;;;###autoload
(defun org-roam-dailies-capture-yesterday (n &optional goto)
"Create an entry in the daily-note for yesteday.
With numeric argument N, use the daily-note N days in the past.
When GOTO is non-nil, go the note without creating an entry."
(interactive "p")
(org-roam-dailies-capture-tomorrow (- n) goto))
;;;###autoload
(defun org-roam-dailies-goto-yesterday (n)
"Find the daily-note for yesterday, creating it if necessary.
With numeric argument N, use the daily-note N days in the
future."
(interactive "p")
(org-roam-dailies-capture-tomorrow (- n) t))
;;;; Date
;;;###autoload
(defun org-roam-dailies-capture-date (&optional goto prefer-future)
"Create an entry in the daily-note for a date using the calendar.
Prefer past dates, unless PREFER-FUTURE is non-nil.
With a `C-u' prefix or when GOTO is non-nil, go the note without
creating an entry."
(interactive "P")
(let ((time (let ((org-read-date-prefer-future prefer-future))
(org-read-date t t nil (if goto
"Find daily-note: "
"Capture to daily-note: ")))))
(org-roam-dailies--capture time goto)))
;;;###autoload
(defun org-roam-dailies-goto-date (&optional prefer-future)
"Find the daily-note for a date using the calendar, creating it if necessary.
Prefer past dates, unless PREFER-FUTURE is non-nil."
(interactive)
(org-roam-dailies-capture-date t prefer-future))
;;;; Navigation
(defun org-roam-dailies-goto-next-note (&optional n)
"Find next daily-note.
With numeric argument N, find note N days in the future. If N is
negative, find note N days in the past."
(interactive "p")
(unless (org-roam-dailies--daily-note-p)
(user-error "Not in a daily-note"))
(setq n (or n 1))
(let* ((dailies (org-roam-dailies--list-files))
(position
(cl-position-if (lambda (candidate)
(string= (buffer-file-name (buffer-base-buffer)) candidate))
dailies))
note)
(unless position
(user-error "Can't find current note file - have you saved it yet?"))
(pcase n
((pred (natnump))
(when (eq position (- (length dailies) 1))
(user-error "Already at newest note")))
((pred (integerp))
(when (eq position 0)
(user-error "Already at oldest note"))))
(setq note (nth (+ position n) dailies))
(find-file note)
(run-hooks 'org-roam-dailies-find-file-hook)))
(defun org-roam-dailies-goto-previous-note (&optional n)
"Find previous daily-note.
With numeric argument N, find note N days in the past. If N is
negative, find note N days in the future."
(interactive "p")
(let ((n (if n (- n) -1)))
(org-roam-dailies-goto-next-note n)))
(defun org-roam-dailies--list-files (&rest extra-files)
"List all files in `org-roam-dailies-directory'.
EXTRA-FILES can be used to append extra files to the list."
(let ((dir (expand-file-name org-roam-dailies-directory org-roam-directory))
(regexp (rx-to-string `(and "." (or ,@org-roam-file-extensions)))))
(append (--remove (let ((file (file-name-nondirectory it)))
(when (or (auto-save-file-name-p file)
(backup-file-name-p file)
(string-match "^\\." file))
it))
(directory-files-recursively dir regexp))
extra-files)))
(defun org-roam-dailies--daily-note-p (&optional file)
"Return t if FILE is an Org-roam daily-note, nil otherwise.
If FILE is not specified, use the current buffer's file-path."
(when-let ((path (expand-file-name
(or file
(buffer-file-name (buffer-base-buffer)))))
(directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
(setq path (expand-file-name path))
(save-match-data
(and
(org-roam-file-p path)
(f-descendant-of-p path directory)))))
;;;###autoload
(defun org-roam-dailies-find-directory ()
"Find and open `org-roam-dailies-directory'."
(interactive)
(find-file (expand-file-name org-roam-dailies-directory org-roam-directory)))
;;; Calendar integration
(defun org-roam-dailies-calendar--file-to-date (file)
"Convert FILE to date.
Return (MONTH DAY YEAR) or nil if not an Org time-string."
(ignore-errors
(cl-destructuring-bind (_ _ _ d m y _ _ _)
(org-parse-time-string
(file-name-sans-extension
(file-name-nondirectory file)))
(list m d y))))
(defun org-roam-dailies-calendar-mark-entries ()
"Mark days in the calendar for which a daily-note is present."
(when (file-exists-p (expand-file-name org-roam-dailies-directory org-roam-directory))
(dolist (date (remove nil
(mapcar #'org-roam-dailies-calendar--file-to-date
(org-roam-dailies--list-files))))
(when (calendar-date-is-visible-p date)
(calendar-mark-visible-date date 'org-roam-dailies-calendar-note)))))
(add-hook 'calendar-today-visible-hook #'org-roam-dailies-calendar-mark-entries)
(add-hook 'calendar-today-invisible-hook #'org-roam-dailies-calendar-mark-entries)
;;; Capture implementation
(add-to-list 'org-roam-capture--template-keywords :override-default-time)
(defun org-roam-dailies--capture (time &optional goto)
"Capture an entry in a daily-note for TIME, creating it if necessary.
When GOTO is non-nil, go the note without creating an entry."
(let ((org-roam-directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
(org-roam-capture- :goto (when goto '(4))
:node (org-roam-node-create)
:templates org-roam-dailies-capture-templates
:props (list :override-default-time time)))
(when goto (run-hooks 'org-roam-dailies-find-file-hook)))
(add-hook 'org-roam-capture-preface-hook #'org-roam-dailies--override-capture-time-h)
(defun org-roam-dailies--override-capture-time-h ()
"Override the `:default-time' with the time from `:override-default-time'."
(prog1 nil
(when (org-roam-capture--get :override-default-time)
(org-capture-put :default-time (org-roam-capture--get :override-default-time)))))
;;; Bindings
(defvar org-roam-dailies-map (make-sparse-keymap)
"Keymap for `org-roam-dailies'.")
(define-prefix-command 'org-roam-dailies-map)
(define-key org-roam-dailies-map (kbd "d") #'org-roam-dailies-goto-today)
(define-key org-roam-dailies-map (kbd "y") #'org-roam-dailies-goto-yesterday)
(define-key org-roam-dailies-map (kbd "t") #'org-roam-dailies-goto-tomorrow)
(define-key org-roam-dailies-map (kbd "n") #'org-roam-dailies-capture-today)
(define-key org-roam-dailies-map (kbd "f") #'org-roam-dailies-goto-next-note)
(define-key org-roam-dailies-map (kbd "b") #'org-roam-dailies-goto-previous-note)
(define-key org-roam-dailies-map (kbd "c") #'org-roam-dailies-goto-date)
(define-key org-roam-dailies-map (kbd "v") #'org-roam-dailies-capture-date)
(define-key org-roam-dailies-map (kbd ".") #'org-roam-dailies-find-directory)
(provide 'org-roam-dailies)
;;; org-roam-dailies.el ends here

283
extensions/org-roam-graph.el Normal file
View File

@ -0,0 +1,283 @@
;;; org-roam-graph.el --- Basic graphing functionality for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This extension implements capability to build and generate graphs in Org-roam
;; with the help of Graphviz.
;;
;;; Code:
(require 'xml) ;xml-escape-string
(require 'org-roam)
;;; Options
(defcustom org-roam-graph-viewer (executable-find "firefox")
"Method to view the org-roam graph.
It may be one of the following:
- a string representing the path to the executable for viewing the graph.
- a function accepting a single argument: the graph file path.
- nil uses `view-file' to view the graph."
:type '(choice
(string :tag "Path to executable")
(function :tag "Function to display graph" eww-open-file)
(const :tag "view-file"))
:group 'org-roam)
(defcustom org-roam-graph-executable "dot"
"Path to graphing executable, or its name."
:type 'string
:group 'org-roam)
(defcustom org-roam-graph-filetype "svg"
"File type to generate when producing graphs."
:type 'string
:group 'org-roam)
(defcustom org-roam-graph-extra-config nil
"Extra options passed to graphviz.
Example:
'((\"rankdir\" . \"LR\"))"
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-edge-extra-config nil
"Extra edge options passed to graphviz.
Example:
'((\"dir\" . \"back\"))"
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-node-extra-config
'(("id" . (("style" . "bold,rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#111111")))
("http" . (("style" . "rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#0A97A6")))
("https" . (("shape" . "rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#0A97A6"))))
"Extra options for graphviz nodes."
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-link-hidden-types
'("file")
"What sort of links to hide from the Org-roam graph."
:type '(repeat string)
:group 'org-roam)
(defcustom org-roam-graph-max-title-length 100
"Maximum length of titles in graph nodes."
:type 'number
:group 'org-roam)
(defcustom org-roam-graph-shorten-titles 'truncate
"Determines how long titles appear in graph nodes.
Recognized values are the symbols `truncate' and `wrap', in which
cases the title will be truncated or wrapped, respectively, if it
is longer than `org-roam-graph-max-title-length'.
All other values including nil will have no effect."
:type '(choice
(const :tag "truncate" truncate)
(const :tag "wrap" wrap)
(const :tag "no" nil))
:group 'org-roam)
;;; Interactive command
;;;###autoload
(defun org-roam-graph (&optional arg node)
"Build and possibly display a graph for NODE.
ARG may be any of the following values:
- nil show the graph.
- `\\[universal-argument]' show the graph for NODE.
- `\\[universal-argument]' N show the graph for NODE limiting nodes to N steps."
(interactive
(list current-prefix-arg
(and current-prefix-arg
(org-roam-node-at-point 'assert))))
(let ((graph (cl-typecase arg
(null (org-roam-graph--dot nil 'all-nodes))
(cons (org-roam-graph--dot (org-roam-graph--connected-component
(org-roam-node-id node) 0)))
(integer (org-roam-graph--dot (org-roam-graph--connected-component
(org-roam-node-id node) (abs arg)))))))
(org-roam-graph--build graph #'org-roam-graph--open)))
;;; Generation and Build process
(defun org-roam-graph--build (graph &optional callback)
"Generate the GRAPH, and execute CALLBACK when process exits successfully.
CALLBACK is passed the graph file as its sole argument."
(unless (stringp org-roam-graph-executable)
(user-error "`org-roam-graph-executable' is not a string"))
(unless (executable-find org-roam-graph-executable)
(user-error (concat "Cannot find executable \"%s\" to generate the graph. "
"Please adjust `org-roam-graph-executable'")
org-roam-graph-executable))
(let* ((temp-dot (make-temp-file "graph." nil ".dot" graph))
(temp-graph (make-temp-file "graph." nil (concat "." org-roam-graph-filetype))))
(org-roam-message "building graph")
(make-process
:name "*org-roam-graph--build-process*"
:buffer "*org-roam-graph--build-process*"
:command `(,org-roam-graph-executable ,temp-dot "-T" ,org-roam-graph-filetype "-o" ,temp-graph)
:sentinel (when callback
(lambda (process _event)
(when (= 0 (process-exit-status process))
(funcall callback temp-graph)))))))
(defun org-roam-graph--dot (&optional edges all-nodes)
"Build the graphviz given the EDGES of the graph.
If ALL-NODES, include also nodes without edges."
(let ((org-roam-directory-temp org-roam-directory)
(nodes-table (make-hash-table :test #'equal))
(seen-nodes (list))
(edges (or edges (org-roam-db-query [:select :distinct [source dest type] :from links]))))
(pcase-dolist (`(,id ,file ,title)
(org-roam-db-query [:select [id file title] :from nodes]))
(puthash id (org-roam-node-create :file file :id id :title title) nodes-table))
(with-temp-buffer
(setq-local org-roam-directory org-roam-directory-temp)
(insert "digraph \"org-roam\" {\n")
(dolist (option org-roam-graph-extra-config)
(insert (org-roam-graph--dot-option option) ";\n"))
(insert (format " edge [%s];\n"
(mapconcat (lambda (var)
(org-roam-graph--dot-option var nil "\""))
org-roam-graph-edge-extra-config
",")))
(pcase-dolist (`(,source ,dest ,type) edges)
(unless (member type org-roam-graph-link-hidden-types)
(pcase-dolist (`(,node ,node-type) `((,source "id")
(,dest ,type)))
(unless (member node seen-nodes)
(insert (org-roam-graph--format-node
(or (gethash node nodes-table) node) node-type))
(push node seen-nodes)))
(insert (format " \"%s\" -> \"%s\";\n"
(xml-escape-string source)
(xml-escape-string dest)))))
(when all-nodes
(maphash (lambda (id node)
(unless (member id seen-nodes)
(insert (org-roam-graph--format-node node "id"))))
nodes-table))
(insert "}")
(buffer-string))))
(defun org-roam-graph--connected-component (id distance)
"Return the edges for all nodes reachable from/connected to ID.
DISTANCE is the maximum distance away from the root node."
(let* ((query
(if (= distance 0)
"
WITH RECURSIVE
links_of(source, dest) AS
(SELECT source, dest FROM links UNION
SELECT dest, source FROM links),
connected_component(source) AS
(SELECT dest FROM links_of WHERE source = $s1 UNION
SELECT dest FROM links_of JOIN connected_component USING(source))
SELECT DISTINCT source, dest, type FROM links
WHERE source IN connected_component OR dest IN connected_component;"
"
WITH RECURSIVE
links_of(source, dest) AS
(SELECT source, dest FROM links UNION
SELECT dest, source FROM links),
connected_component(source, trace) AS
(VALUES ($s1 , json_array($s1)) UNION
SELECT lo.dest, json_insert(cc.trace, '$[' || json_array_length(cc.trace) || ']', lo.dest) FROM
connected_component AS cc JOIN links_of AS lo USING(source)
WHERE (
-- Avoid cycles by only visiting each node once.
(SELECT count(*) FROM json_each(cc.trace) WHERE json_each.value == lo.dest) == 0
-- Note: BFS is cut off early here.
AND json_array_length(cc.trace) < $s2)),
nodes(source) as (SELECT DISTINCT source
FROM connected_component GROUP BY source ORDER BY min(json_array_length(trace)))
SELECT DISTINCT source, dest, type FROM links WHERE source IN nodes OR dest IN nodes;")))
(org-roam-db-query query id distance)))
(defun org-roam-graph--dot-option (option &optional wrap-key wrap-val)
"Return dot string of form KEY=VAL for OPTION cons.
If WRAP-KEY is non-nil it wraps the KEY.
If WRAP-VAL is non-nil it wraps the VAL."
(concat wrap-key (car option) wrap-key
"="
wrap-val (cdr option) wrap-val))
(defun org-roam-graph--format-node (node type)
"Return a graphviz NODE with TYPE.
Handles both Org-roam nodes, and string nodes (e.g. urls)."
(let (node-id node-properties)
(if (org-roam-node-p node)
(let* ((title (org-roam-quote-string (org-roam-node-title node)))
(shortened-title
(org-roam-quote-string
(pcase org-roam-graph-shorten-titles
(`truncate (truncate-string-to-width title org-roam-graph-max-title-length nil nil "..."))
(`wrap (s-word-wrap org-roam-graph-max-title-length title))
(_ title)))))
(setq node-id (org-roam-node-id node)
node-properties `(("label" . ,shortened-title)
("URL" . ,(concat "org-protocol://roam-node?node="
(url-hexify-string (org-roam-node-id node))))
("tooltip" . ,(xml-escape-string title)))))
(setq node-id node
node-properties (append `(("label" . ,(concat type ":" node)))
(when (member type (list "http" "https"))
`(("URL" . ,(xml-escape-string (concat type ":" node))))))))
(format "\"%s\" [%s];\n"
node-id
(mapconcat (lambda (n)
(org-roam-graph--dot-option n nil "\""))
(append (cdr (assoc type org-roam-graph-node-extra-config))
node-properties) ","))))
(defun org-roam-graph--open (file)
"Open FILE using `org-roam-graph-viewer' with `view-file' as a fallback."
(pcase org-roam-graph-viewer
((pred stringp)
(if (executable-find org-roam-graph-viewer)
(condition-case err
(call-process org-roam-graph-viewer nil 0 nil file)
(error (user-error "Failed to open org-roam graph: %s" err)))
(user-error "Executable not found: \"%s\"" org-roam-graph-viewer)))
((pred functionp) (funcall org-roam-graph-viewer file))
('nil (view-file file))
(_ (signal 'wrong-type-argument `((functionp stringp null) ,org-roam-graph-viewer)))))
(provide 'org-roam-graph)
;;; org-roam-graph.el ends here

96
extensions/org-roam-overlay.el Normal file
View File

@ -0,0 +1,96 @@
;;; org-roam-overlay.el --- Link overlay for [id:] links to Org-roam nodes -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This extension provides allows to render [[id:]] links that don't have an
;; asscoiated descriptor with an overlay that displays the node's current title.
;;
;;; Code:
(require 'org-roam)
(defface org-roam-overlay
'((((class color) (background light))
:background "grey90" :box (:line-width -1 :color "black"))
(((class color) (background dark))
:background "grey10" :box (:line-width -1 :color "white")))
"Face for the Org-roam overlay."
:group 'org-roam-faces)
(defun org-roam-overlay--make (l r &rest props)
"Make an overlay from L to R with PROPS."
(let ((o (make-overlay l (or r l))))
(overlay-put o 'category 'org-roam)
(while props (overlay-put o (pop props) (pop props)))
o))
(defun org-roam-overlay-make-link-overlay (link)
"Create overlay for LINK."
(save-excursion
(save-match-data
(let* ((type (org-element-property :type link))
(id (org-element-property :path link))
(pos (org-element-property :end link))
(desc-p (org-element-property :contents-begin link))
node)
(when (and (string-equal type "id")
(setq node (org-roam-node-from-id id))
(not desc-p))
(org-roam-overlay--make
pos pos
'after-string (format "%s "
(propertize (org-roam-node-title node)
'face 'org-roam-overlay))))))))
(defun org-roam-overlay-enable ()
"Enable Org-roam overlays."
(org-roam-db-map-links
(list #'org-roam-overlay-make-link-overlay)))
(defun org-roam-overlay-disable ()
"Disable Org-roam overlays."
(remove-overlays nil nil 'category 'org-roam))
(defun org-roam-overlay-redisplay ()
"Redisplay Org-roam overlays."
(org-roam-overlay-disable)
(org-roam-overlay-enable))
(define-minor-mode org-roam-overlay-mode
"Overlays for Org-roam ID links.
Org-roam overlay mode is a minor mode. When enabled,
overlay displaying the node's title is displayed."
:lighter " org-roam-overlay"
(if org-roam-overlay-mode
(progn
(org-roam-overlay-enable)
(add-hook 'after-save-hook #'org-roam-overlay-redisplay nil t))
(org-roam-overlay-disable)
(remove-hook 'after-save-hook #'org-roam-overlay-redisplay t)))
(provide 'org-roam-overlay)
;;; org-roam-overlay.el ends here

192
extensions/org-roam-protocol.el Normal file
View File

@ -0,0 +1,192 @@
;;; org-roam-protocol.el --- Protocol handler for roam:// links -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This extension extends `org-protocol', adding custom Org-roam handlers to it
;; to provide the next new protocols:
;;
;; 1. "roam-node": This protocol simply opens the node given by the node ID
;; 2. "roam-ref": This protocol creates or opens the node with the given REF
;;
;; You can find detailed instructions on how to setup the protocol in the
;; documentation for Org-roam.
;;
;;; Code:
(require 'org-protocol)
(require 'ol) ;; for org-link-decode
(require 'org-roam)
;;; Options
(defcustom org-roam-protocol-store-links nil
"Whether to store links when capturing websites with `org-roam-protocol'."
:type 'boolean
:group 'org-roam)
(defcustom org-roam-capture-ref-templates
'(("r" "ref" plain "%?"
:if-new (file+head "${slug}.org"
"#+title: ${title}")
:unnarrowed t))
"The Org-roam templates used during a capture from the roam-ref protocol.
See `org-roam-capture-templates' for the template documentation."
:group 'org-roam
:type '(repeat
(choice (list :tag "Multikey description"
(string :tag "Keys ")
(string :tag "Description"))
(list :tag "Template entry"
(string :tag "Keys ")
(string :tag "Description ")
(choice :tag "Capture Type " :value entry
(const :tag "Org entry" entry)
(const :tag "Plain list item" item)
(const :tag "Checkbox item" checkitem)
(const :tag "Plain text" plain)
(const :tag "Table line" table-line))
(choice :tag "Template "
(string)
(list :tag "File"
(const :format "" file)
(file :tag "Template file"))
(list :tag "Function"
(const :format "" function)
(function :tag "Template function")))
(plist :inline t
;; Give the most common options as checkboxes
:options (((const :format "%v " :if-new)
(choice :tag "Node location"
(list :tag "File"
(const :format "" file)
(string :tag " File"))
(list :tag "File & Head Content"
(const :format "" file+head)
(string :tag " File")
(string :tag " Head Content"))
(list :tag "File & Outline path"
(const :format "" file+olp)
(string :tag " File")
(list :tag "Outline path"
(repeat (string :tag "Headline"))))
(list :tag "File & Head Content & Outline path"
(const :format "" file+head+olp)
(string :tag " File")
(string :tag " Head Content")
(list :tag "Outline path"
(repeat (string :tag "Headline"))))))
((const :format "%v " :prepend) (const t))
((const :format "%v " :immediate-finish) (const t))
((const :format "%v " :jump-to-captured) (const t))
((const :format "%v " :empty-lines) (const 1))
((const :format "%v " :empty-lines-before) (const 1))
((const :format "%v " :empty-lines-after) (const 1))
((const :format "%v " :clock-in) (const t))
((const :format "%v " :clock-keep) (const t))
((const :format "%v " :clock-resume) (const t))
((const :format "%v " :time-prompt) (const t))
((const :format "%v " :tree-type) (const week))
((const :format "%v " :unnarrowed) (const t))
((const :format "%v " :table-line-pos) (string))
((const :format "%v " :kill-buffer) (const t))))))))
;;; Handlers
(defun org-roam-protocol-open-ref (info)
"Process an org-protocol://roam-ref?ref= style url with INFO.
It opens or creates a note with the given ref.
javascript:location.href = \\='org-protocol://roam-ref?template=r&ref=\\='+ \\
encodeURIComponent(location.href) + \\='&title=\\=' + \\
encodeURIComponent(document.title) + \\='&body=\\=' + \\
encodeURIComponent(window.getSelection())"
(unless (plist-get info :ref)
(user-error "No ref key provided"))
(org-roam-plist-map! (lambda (k v)
(org-link-decode
(if (equal k :ref)
(org-protocol-sanitize-uri v)
v))) info)
(when org-roam-protocol-store-links
(push (list (plist-get info :ref)
(plist-get info :title)) org-stored-links))
(org-link-store-props :type (and (string-match org-link-plain-re
(plist-get info :ref))
(match-string 1 (plist-get info :ref)))
:link (plist-get info :ref)
:annotation (org-link-make-string (plist-get info :ref)
(or (plist-get info :title)
(plist-get info :ref)))
:initial (or (plist-get info :body) ""))
(raise-frame)
(org-roam-capture-
:keys (plist-get info :template)
:node (org-roam-node-create :title (plist-get info :title))
:info (list :ref (plist-get info :ref)
:body (plist-get info :body))
:templates org-roam-capture-ref-templates)
nil)
(defun org-roam-protocol-open-node (info)
"This handler simply opens the file with emacsclient.
INFO is a plist containing additional information passed by the protocol URL.
It should contain the FILE key, pointing to the path of the file to open.
Example protocol string:
org-protocol://roam-node?node=uuid"
(when-let ((node (plist-get info :node)))
(raise-frame)
(org-roam-node-visit (org-roam-populate (org-roam-node-create :id node)) nil 'force))
nil)
(push '("org-roam-ref" :protocol "roam-ref" :function org-roam-protocol-open-ref)
org-protocol-protocol-alist)
(push '("org-roam-node" :protocol "roam-node" :function org-roam-protocol-open-node)
org-protocol-protocol-alist)
;;; Capture implementation
(add-hook 'org-roam-capture-preface-hook #'org-roam-protocol--try-capture-to-ref-h)
(defun org-roam-protocol--try-capture-to-ref-h ()
"Try to capture to an existing node that match the ref."
(when-let ((node (and (plist-get org-roam-capture--info :ref)
(org-roam-node-from-ref
(plist-get org-roam-capture--info :ref)))))
(set-buffer (org-capture-target-buffer (org-roam-node-file node)))
(goto-char (org-roam-node-point node))
(widen)
(org-roam-node-id node)))
(add-hook 'org-roam-capture-new-node-hook #'org-roam-protocol--insert-captured-ref-h)
(defun org-roam-protocol--insert-captured-ref-h ()
"Insert the ref if any."
(when-let ((ref (plist-get org-roam-capture--info :ref)))
(org-roam-ref-add ref)))
(provide 'org-roam-protocol)
;;; org-roam-protocol.el ends here

1079
makem.sh
View File

File diff suppressed because it is too large Load Diff

33
mkdocs.yml
View File

@ -1,33 +0,0 @@
site_name: "Org-Roam: Roam + Org-Mode = ♥"
repo_url: https://github.com/jethrokuan/org-roam/
edit_uri: edit/master/doc/
copyright: "Copyright (C) 2020 Jethro Kuan and contributors"
docs_dir: doc
nav:
- Home: index.md
- A Tour of Org-Roam: tour.md
- Installation: installation.md
- Configuration: configuration.md
- Ecosystem: ecosystem.md
- Similar Packages: comparison.md
- "Appendix: Note-taking Workflow": notetaking_workflow.md
- "Appendix: Graph Setup": graph_setup.md
markdown_extensions:
- admonition
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
theme:
name: 'material'
palette:
primary: 'deep purple'
accent: 'deep purple'

767
org-roam-capture.el Normal file
View File

@ -0,0 +1,767 @@
;;; org-roam-capture.el --- Capture functionality -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This module provides `org-capture' functionality for Org-roam. With this
;; module the user can capture new nodes or capture new content to existing
;; nodes.
;;
;;; Code:
(require 'org-roam)
;;;; Declarations
(defvar org-end-time-was-given)
;;; Options
(defcustom org-roam-capture-templates
'(("d" "default" plain "%?"
:if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
"#+title: ${title}\n")
:unnarrowed t))
"Templates for the creation of new entries within Org-roam.
Each entry is a list with the following items:
keys The keys that will select the template, as a string, characters only, for
example \"a\" for a template to be selected with a single key, or
\"bt\" for selection with two keys. When using several keys, keys
using the same prefix must be together in the list and preceded by a
2-element entry explaining the prefix key, for example:
(\"b\" \"Templates for marking stuff to buy\")
The \"C\" key is used by default for quick access to the customization of
the template variable. But if you want to use that key for a template,
you can.
description A short string describing the template, which will be shown
during selection.
type The type of entry. Valid types are:
entry an Org node, with a headline. Will be filed
as the child of the target entry or as a
top level entry. Its default template is:
\"* %?\n %a\"
item a plain list item, will be placed in the
first plain list at the target location.
Its default template is:
\"- %?\"
checkitem a checkbox item. This differs from the
plain list item only in so far as it uses a
different default template. Its default
template is:
\"- [ ] %?\"
table-line a new line in the first table at target location.
Its default template is:
\"| %? |\"
plain text to be inserted as it is.
template The template for creating the capture item.
If it is an empty string or nil, a default template based on
the entry type will be used (see the \"type\" section above).
Instead of a string, this may also be one of:
(file \"/path/to/template-file\")
(function function-returning-the-template)
in order to get a template from a file, or dynamically
from a function.
The template contains a compulsory :if-new property. This determines the
location of the new node. The :if-new property contains a list, supporting
the following options:
(file \"path/to/file\")
The file will be created, and prescribed an ID.
(file+head \"path/to/file\" \"head content\")
The file will be created, prescribed an ID, and head content will be
inserted into the file.
(file+olp \"path/to/file\" (\"h1\" \"h2\"))
The file will be created, prescribed an ID. The OLP (h1, h2) will be
created, and the point placed after.
(file+head+olp \"path/to/file\" \"head content\" (\"h1\" \"h2\"))
The file will be created, prescribed an ID. Head content will be
inserted at the start of the file. The OLP (h1, h2) will be created,
and the point placed after.
(file+datetree \"path/to/file\" day)
The file will be created, prescribed an ID. Head content will be
inserted at the start of the file. The datetree will be created,
available options are day, week, month.
(node \"title or alias or ID of an existing node\")
The point will be placed for an existing node, based on either, its
title, alias or ID.
The rest of the entry is a property list of additional options. Recognized
properties are:
:prepend Normally newly captured information will be appended at
the target location (last child, last table line,
last list item...). Setting this property will
change that.
:immediate-finish When set, do not offer to edit the information, just
file it away immediately. This makes sense if the
template only needs information that can be added
automatically.
:jump-to-captured When set, jump to the captured entry when finished.
:empty-lines Set this to the number of lines that should be inserted
before and after the new item. Default 0, only common
other value is 1.
:empty-lines-before Set this to the number of lines that should be inserted
before the new item. Overrides :empty-lines for the
number lines inserted before.
:empty-lines-after Set this to the number of lines that should be inserted
after the new item. Overrides :empty-lines for the
number of lines inserted after.
:clock-in Start the clock in this item.
:clock-keep Keep the clock running when filing the captured entry.
:clock-resume Start the interrupted clock when finishing the capture.
Note that :clock-keep has precedence over :clock-resume.
When setting both to t, the current clock will run and
the previous one will not be resumed.
:time-prompt Prompt for a date/time to be used for date/week trees
and when filling the template.
:tree-type When `week', make a week tree instead of the month-day
tree. When `month', make a month tree instead of the
month-day tree.
:unnarrowed Do not narrow the target buffer, simply show the
full buffer. Default is to narrow it so that you
only see the new stuff.
:table-line-pos Specification of the location in the table where the
new line should be inserted. It should be a string like
\"II-3\", meaning that the new line should become the
third line before the second horizontal separator line.
:kill-buffer If the target file was not yet visited by a buffer when
capture was invoked, kill the buffer again after capture
is finalized.
:no-save Do not save the target file after finishing the capture.
The template defines the text to be inserted. Often this is an
Org mode entry (so the first line should start with a star) that
will be filed as a child of the target headline. It can also be
freely formatted text. Furthermore, the following %-escapes will
be replaced with content and expanded:
%[pathname] Insert the contents of the file given by
`pathname'. These placeholders are expanded at the very
beginning of the process so they can be used to extend the
current template.
%(sexp) Evaluate elisp `(sexp)' and replace it with the results.
Only placeholders pre-existing within the template, or
introduced with %[pathname] are expanded this way. Since this
happens after expanding non-interactive %-escapes, those can
be used to fill the expression.
%<...> The result of `format-time-string' on the ... format specification.
%t Time stamp, date only. The time stamp is the current time,
except when called from agendas with `\\[org-agenda-capture]' or
with `org-capture-use-agenda-date' set.
%T Time stamp as above, with date and time.
%u, %U Like the above, but inactive time stamps.
%i Initial content, copied from the active region. If
there is text before %i on the same line, such as
indentation, and %i is not inside a %(sexp), that prefix
will be added before every line in the inserted text.
%a Annotation, normally the link created with `org-store-link'.
%A Like %a, but prompt for the description part.
%l Like %a, but only insert the literal link.
%L Like %l, but without brackets (the link content itself).
%c Current kill ring head.
%x Content of the X clipboard.
%k Title of currently clocked task.
%K Link to currently clocked task.
%n User name (taken from the variable `user-full-name').
%f File visited by current buffer when `org-capture' was called.
%F Full path of the file or directory visited by current buffer.
%:keyword Specific information for certain link types, see below.
%^g Prompt for tags, with completion on tags in target file.
%^G Prompt for tags, with completion on all tags in all agenda files.
%^t Like %t, but prompt for date. Similarly %^T, %^u, %^U.
You may define a prompt like: %^{Please specify birthday}t.
The default date is that of %t, see above.
%^C Interactive selection of which kill or clip to use.
%^L Like %^C, but insert as link.
%^{prop}p Prompt the user for a value for property `prop'.
A default value can be specified like this:
%^{prop|default}p.
%^{prompt} Prompt the user for a string and replace this sequence with it.
A default value and a completion table can be specified like this:
%^{prompt|default|completion2|completion3|...}.
%? After completing the template, position cursor here.
%\\1 ... %\\N Insert the text entered at the nth %^{prompt}, where N
is a number, starting from 1.
Apart from these general escapes, you can access information specific to
the link type that is created. For example, calling `org-capture' in emails
or in Gnus will record the author and the subject of the message, which you
can access with \"%:from\" and \"%:subject\", respectively. Here is a
complete list of what is recorded for each link type.
Link type | Available information
------------------------+------------------------------------------------------
bbdb | %:type %:name %:company
vm, wl, mh, mew, rmail, | %:type %:subject %:message-id
gnus | %:from %:fromname %:fromaddress
| %:to %:toname %:toaddress
| %:fromto (either \"to NAME\" or \"from NAME\")
| %:date %:date-timestamp (as active timestamp)
| %:date-timestamp-inactive (as inactive timestamp)
gnus | %:group, for messages also all email fields
eww, w3, w3m | %:type %:url
info | %:type %:file %:node
calendar | %:type %:date
When you need to insert a literal percent sign in the template,
you can escape ambiguous cases with a backward slash, e.g., \\%i.
In addition to all of the above, Org-roam supports additional
substitutions within its templates. \"${foo}\" will look for the
foo property in the Org-roam node (see the `org-roam-node'). If
the property does not exist, the user will be prompted to fill in
the string value.
Org-roam templates are NOT compatible with regular Org capture:
they rely on additional hacks and hooks to achieve the
streamlined user experience in Org-roam."
:group 'org-roam
:type '(repeat
(choice (list :tag "Multikey description"
(string :tag "Keys ")
(string :tag "Description"))
(list :tag "Template entry"
(string :tag "Keys ")
(string :tag "Description ")
(choice :tag "Capture Type " :value entry
(const :tag "Org entry" entry)
(const :tag "Plain list item" item)
(const :tag "Checkbox item" checkitem)
(const :tag "Plain text" plain)
(const :tag "Table line" table-line))
(choice :tag "Template "
(string)
(list :tag "File"
(const :format "" file)
(file :tag "Template file"))
(list :tag "Function"
(const :format "" function)
(function :tag "Template function")))
(plist :inline t
;; Give the most common options as checkboxes
:options (((const :format "%v " :if-new)
(choice :tag "Node location"
(list :tag "File"
(const :format "" file)
(string :tag " File"))
(list :tag "File & Head Content"
(const :format "" file+head)
(string :tag " File")
(string :tag " Head Content"))
(list :tag "File & Outline path"
(const :format "" file+olp)
(string :tag " File")
(list :tag "Outline path"
(repeat (string :tag "Headline"))))
(list :tag "File & Head Content & Outline path"
(const :format "" file+head+olp)
(string :tag " File")
(string :tag " Head Content")
(list :tag "Outline path"
(repeat (string :tag "Headline"))))))
((const :format "%v " :prepend) (const t))
((const :format "%v " :immediate-finish) (const t))
((const :format "%v " :jump-to-captured) (const t))
((const :format "%v " :empty-lines) (const 1))
((const :format "%v " :empty-lines-before) (const 1))
((const :format "%v " :empty-lines-after) (const 1))
((const :format "%v " :clock-in) (const t))
((const :format "%v " :clock-keep) (const t))
((const :format "%v " :clock-resume) (const t))
((const :format "%v " :time-prompt) (const t))
((const :format "%v " :tree-type) (const week))
((const :format "%v " :unnarrowed) (const t))
((const :format "%v " :table-line-pos) (string))
((const :format "%v " :kill-buffer) (const t))))))))
(defcustom org-roam-capture-new-node-hook nil
"Normal-mode hooks run when a new Org-roam node is created.
The current point is the point of the new node.
The hooks must not move the point."
:group 'org-roam
:type 'hook)
(defvar org-roam-capture-preface-hook nil
"Hook run when Org-roam tries to determine capture location of the node.
If any hook returns a value (which should be an ID), all hooks
after it are ignored.
With this hook you can hijack controls over the location of the
node for which the capture process is currently running for, or
use to just perform an arbitrary side effect, e.g. modify the
state related to the capture process. See `org-roam-protocol' and
`org-roam-dailies' as examples for what and how this hook is used
for.
If you're trying to perform the hijack, it's mandatory for you to:
1. Set the currently active buffer for editing operations using
`org-capture-target-buffer'.
2. Place the point in this buffer from where the location starts
from (e.g. if it's a file based node it should be the BOB,
otherwise it should be the position from where the heading
based node starts from).
3. Return the ID (as a string) of the capturing node.
If you use this hook for any other purpose, but not the hijack,
it's mandatory that you should return nil as the return value; so
the capture process would be able to setup the capture buffer.
If you need to do something when you capture new nodes, use
`org-roam-capture-new-node-hook' instead of this hook.
WARNING: This hook is primarily designed for the usage by the
extensions and packages, and requires understanding of the
internal capture process. If you don't understand it, you should
learn these internals before using this or use it at your own
risk breaking things.")
;;; Variables
(defvar org-roam-capture--node nil
"The node passed during an Org-roam capture.
This variable is populated dynamically, and is only non-nil
during the Org-roam capture process.")
(defvar org-roam-capture--info nil
"A property-list of additional information passed to the Org-roam template.
This variable is populated dynamically, and is only non-nil
during the Org-roam capture process.")
(defconst org-roam-capture--template-keywords (list :if-new :id :link-description :call-location
:region)
"Keywords used in `org-roam-capture-templates' specific to Org-roam.")
;;; Main entry point
;;;###autoload
(cl-defun org-roam-capture- (&key goto keys node info props templates)
"Main entry point of `org-roam-capture' module.
GOTO and KEYS correspond to `org-capture' arguments.
INFO is a plist for filling up Org-roam's capture templates.
NODE is an `org-roam-node' construct containing information about the node.
PROPS is a plist containing additional Org-roam properties for each template.
TEMPLATES is a list of org-roam templates."
(let* ((props (plist-put props :call-location (point-marker)))
(org-capture-templates
(mapcar (lambda (template)
(org-roam-capture--convert-template template props))
(or templates org-roam-capture-templates)))
(org-roam-capture--node node)
(org-roam-capture--info info))
(when (and (not keys)
(= (length org-capture-templates) 1))
(setq keys (caar org-capture-templates)))
(org-capture goto keys)))
;;;###autoload
(cl-defun org-roam-capture (&optional goto keys &key filter-fn templates info)
"Launches an `org-capture' process for a new or existing node.
This uses the templates defined at `org-roam-capture-templates'.
Arguments GOTO and KEYS see `org-capture'.
FILTER-FN is a function to filter out nodes: it takes an `org-roam-node',
and when nil is returned the node will be filtered out.
The TEMPLATES, if provided, override the list of capture templates (see
`org-roam-capture-'.)
The INFO, if provided, is passed along to the underlying `org-roam-capture-'."
(interactive "P")
(let ((node (org-roam-node-read nil filter-fn)))
(org-roam-capture- :goto goto
:info info
:keys keys
:templates templates
:node node
:props '(:immediate-finish nil))))
;;; Capture process
(defun org-roam-capture-p ()
"Return t if the current capture process is an Org-roam capture.
This function is to only be called when `org-capture-plist' is
valid for the capture (i.e. initialization, and finalization of
the capture)."
(plist-get org-capture-plist :org-roam))
(defun org-roam-capture--get (keyword)
"Get the value for KEYWORD from the `org-roam-capture-template'."
(plist-get (plist-get org-capture-plist :org-roam) keyword))
(defun org-roam-capture--put (&rest stuff)
"Put properties from STUFF into the `org-roam-capture-template'."
(let ((p (plist-get org-capture-plist :org-roam)))
(while stuff
(setq p (plist-put p (pop stuff) (pop stuff))))
(setq org-capture-plist
(plist-put org-capture-plist :org-roam p))))
;;;; Capture target
(defun org-roam-capture--prepare-buffer ()
"Prepare the capture buffer for the current Org-roam based capture template.
This function will initialize and setup the capture buffer,
create the target node (`:if-new') if it doesn't exist, and place
the point for further processing by `org-capture'.
Note: During the capture process this function is run by
`org-capture-set-target-location', as a (function ...) based
capture target."
(let ((id (cond ((run-hook-with-args-until-success 'org-roam-capture-preface-hook))
((and (org-roam-node-file org-roam-capture--node)
(org-roam-node-point org-roam-capture--node))
(set-buffer (org-capture-target-buffer (org-roam-node-file org-roam-capture--node)))
(goto-char (org-roam-node-point org-roam-capture--node))
(widen)
(org-roam-node-id org-roam-capture--node))
(t
(org-roam-capture--setup-target-location)))))
(org-roam-capture--adjust-point-for-capture-type)
(org-capture-put :template
(org-roam-capture--fill-template (org-capture-get :template)))
(org-roam-capture--put :id id)
(org-roam-capture--put :finalize (or (org-capture-get :finalize)
(org-roam-capture--get :finalize)))))
(defun org-roam-capture--setup-target-location ()
"Initialize the buffer, and goto the location of the new capture.
Return the ID of the location."
(let (p new-file-p)
(pcase (or (org-roam-capture--get :if-new)
(user-error "Template needs to specify `:if-new'"))
(`(file ,path)
(setq path (expand-file-name
(string-trim (org-roam-capture--fill-template path t))
org-roam-directory))
(setq new-file-p (org-roam-capture--new-file-p path))
(when new-file-p (org-roam-capture--put :new-file path))
(set-buffer (org-capture-target-buffer path))
(widen)
(setq p (goto-char (point-min))))
(`(file+olp ,path ,olp)
(setq path (expand-file-name
(string-trim (org-roam-capture--fill-template path t))
org-roam-directory))
(setq new-file-p (org-roam-capture--new-file-p path))
(when new-file-p (org-roam-capture--put :new-file path))
(set-buffer (org-capture-target-buffer path))
(setq p (point-min))
(let ((m (org-roam-capture-find-or-create-olp olp)))
(goto-char m))
(widen))
(`(file+head ,path ,head)
(setq path (expand-file-name
(string-trim (org-roam-capture--fill-template path t))
org-roam-directory))
(setq new-file-p (org-roam-capture--new-file-p path))
(set-buffer (org-capture-target-buffer path))
(when new-file-p
(org-roam-capture--put :new-file path)
(insert (org-roam-capture--fill-template head t)))
(widen)
(setq p (goto-char (point-min))))
(`(file+head+olp ,path ,head ,olp)
(setq path (expand-file-name
(string-trim (org-roam-capture--fill-template path t))
org-roam-directory))
(setq new-file-p (org-roam-capture--new-file-p path))
(set-buffer (org-capture-target-buffer path))
(widen)
(when new-file-p
(org-roam-capture--put :new-file path)
(insert (org-roam-capture--fill-template head t)))
(setq p (point-min))
(let ((m (org-roam-capture-find-or-create-olp olp)))
(goto-char m)))
(`(file+datetree ,path ,tree-type)
(setq path (expand-file-name
(string-trim (org-roam-capture--fill-template path t))
org-roam-directory))
(require 'org-datetree)
(widen)
(set-buffer (org-capture-target-buffer path))
(unless (file-exists-p path)
(org-roam-capture--put :new-file path))
(funcall
(pcase tree-type
(`week #'org-datetree-find-iso-week-create)
(`month #'org-datetree-find-month-create)
(_ #'org-datetree-find-date-create))
(calendar-gregorian-from-absolute
(cond
(org-overriding-default-time
;; Use the overriding default time.
(time-to-days org-overriding-default-time))
((org-capture-get :default-time)
(time-to-days (org-capture-get :default-time)))
((org-capture-get :time-prompt)
;; Prompt for date. Bind `org-end-time-was-given' so
;; that `org-read-date-analyze' handles the time range
;; case and returns `prompt-time' with the start value.
(let* ((org-time-was-given nil)
(org-end-time-was-given nil)
(prompt-time (org-read-date
nil t nil "Date for tree entry:")))
(org-capture-put
:default-time
(if (or org-time-was-given
(= (time-to-days prompt-time) (org-today)))
prompt-time
;; Use 00:00 when no time is given for another
;; date than today?
(apply #'encode-time 0 0
org-extend-today-until
(cl-cdddr (decode-time prompt-time)))))
(time-to-days prompt-time)))
(t
;; Current date, possibly corrected for late night
;; workers.
(org-today)))))
(setq p (point)))
(`(node ,title-or-id)
;; first try to get ID, then try to get title/alias
(let ((node (or (org-roam-node-from-id title-or-id)
(org-roam-node-from-title-or-alias title-or-id)
(user-error "No node with title or id \"%s\"" title-or-id))))
(set-buffer (org-capture-target-buffer (org-roam-node-file node)))
(goto-char (org-roam-node-point node))
(setq p (org-roam-node-point node)))))
;; Setup `org-id' for the current capture target and return it back to the
;; caller.
(save-excursion
(goto-char p)
(when-let* ((node org-roam-capture--node)
(id (org-roam-node-id node)))
(org-entry-put p "ID" id))
(prog1
(org-id-get-create)
(run-hooks 'org-roam-capture-new-node-hook)))))
(defun org-roam-capture--new-file-p (path)
"Return t if PATH is for a new file with no visiting buffer."
(not (or (file-exists-p path)
(org-find-base-buffer-visiting path))))
(defun org-roam-capture-find-or-create-olp (olp)
"Return a marker pointing to the entry at OLP in the current buffer.
If OLP does not exist, create it. If anything goes wrong, throw
an error, and if you need to do something based on this error,
you can catch it with `condition-case'."
(let* ((level 1)
(lmin 1)
(lmax 1)
(start (point-min))
(end (point-max))
found flevel)
(unless (derived-mode-p 'org-mode)
(error "Buffer %s needs to be in Org mode" (current-buffer)))
(org-with-wide-buffer
(goto-char start)
(dolist (heading olp)
(let ((re (format org-complex-heading-regexp-format
(regexp-quote heading)))
(cnt 0))
(while (re-search-forward re end t)
(setq level (- (match-end 1) (match-beginning 1)))
(when (and (>= level lmin) (<= level lmax))
(setq found (match-beginning 0) flevel level cnt (1+ cnt))))
(when (> cnt 1)
(error "Heading not unique on level %d: %s" lmax heading))
(when (= cnt 0)
;; Create heading if it doesn't exist
(goto-char end)
(unless (bolp) (newline))
(let (org-insert-heading-respect-content)
(org-insert-heading nil nil t))
(unless (= lmax 1)
(dotimes (_ level) (org-do-demote)))
(insert heading)
(setq end (point))
(goto-char start)
(while (re-search-forward re end t)
(setq level (- (match-end 1) (match-beginning 1)))
(when (and (>= level lmin) (<= level lmax))
(setq found (match-beginning 0) flevel level cnt (1+ cnt))))))
(goto-char found)
(setq lmin (1+ flevel) lmax (+ lmin (if org-odd-levels-only 1 0)))
(setq start found
end (save-excursion (org-end-of-subtree t t))))
(point-marker))))
(defun org-roam-capture--adjust-point-for-capture-type (&optional pos)
"Reposition the point for template insertion dependently on the capture type.
Return the newly adjusted position of `point'.
POS is the current position of point (an integer) inside the
currently active capture buffer, where the adjustment should
start to begin from. If it's nil, then it will default to
the current value of `point'."
(or pos (setq pos (point)))
(goto-char pos)
(let ((location-type (if (= pos 1) 'beginning-of-file 'heading-at-point)))
(and (eq location-type 'heading-at-point)
(cl-assert (org-at-heading-p)))
(pcase (org-capture-get :type)
(`plain
(cl-case location-type
(beginning-of-file
(if (org-capture-get :prepend)
(let ((el (org-element-at-point)))
(while (and (not (eobp))
(memq (org-element-type el)
'(drawer property-drawer keyword comment comment-block horizontal-rule)))
(goto-char (org-element-property :end el))
(setq el (org-element-at-point))))
(goto-char (org-entry-end-position))))
(heading-at-point
(if (org-capture-get :prepend)
(org-end-of-meta-data t)
(goto-char (org-entry-end-position))))))))
(point))
;;;; Finalizers
(add-hook 'org-capture-prepare-finalize-hook #'org-roam-capture--install-finalize-h)
(defun org-roam-capture--install-finalize-h ()
"Install `org-roam-capture--finalize' if the capture is an Org-roam capture."
(when (org-roam-capture-p)
(add-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
(defun org-roam-capture--finalize ()
"Finalize the `org-roam-capture' process."
(when-let ((region (org-roam-capture--get :region)))
(org-roam-unshield-region (car region) (cdr region)))
(if org-note-abort
(when-let ((new-file (org-roam-capture--get :new-file)))
(org-roam-message "Deleting file for aborted capture %s" new-file)
(when (find-buffer-visiting new-file)
(kill-buffer (find-buffer-visiting new-file)))
(delete-file new-file))
(when-let* ((finalize (org-roam-capture--get :finalize))
(org-roam-finalize-fn (intern (concat "org-roam-capture--finalize-"
(symbol-name finalize)))))
(if (functionp org-roam-finalize-fn)
(funcall org-roam-finalize-fn)
(funcall finalize))))
(remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize))
(defun org-roam-capture--finalize-find-file ()
"Visit the buffer after Org-capture is done.
This function is to be called in the Org-capture finalization process.
ID is unused."
(switch-to-buffer (org-capture-get :buffer)))
(defun org-roam-capture--finalize-insert-link ()
"Insert a link to ID into the buffer where Org-capture was called.
ID is the Org id of the newly captured content.
This function is to be called in the Org-capture finalization process."
(when-let* ((mkr (org-roam-capture--get :call-location))
(buf (marker-buffer mkr)))
(with-current-buffer buf
(when-let ((region (org-roam-capture--get :region)))
(org-roam-unshield-region (car region) (cdr region))
(delete-region (car region) (cdr region))
(set-marker (car region) nil)
(set-marker (cdr region) nil))
(org-with-point-at mkr
(insert (org-link-make-string (concat "id:" (org-roam-capture--get :id))
(org-roam-capture--get :link-description)))))))
;;;; Processing of the capture templates
(defun org-roam-capture--fill-template (template &optional org-capture-p)
"Expand TEMPLATE and return it.
It expands ${var} occurrences in TEMPLATE. When ORG-CAPTURE-P,
also run Org-capture's template expansion."
(funcall (if org-capture-p #'org-capture-fill-template #'identity)
(org-roam-format-template
template
(lambda (key default-val)
(let ((fn (intern key))
(node-fn (intern (concat "org-roam-node-" key)))
(ksym (intern (concat ":" key))))
(cond
((fboundp fn)
(funcall fn org-roam-capture--node))
((fboundp node-fn)
(funcall node-fn org-roam-capture--node))
((plist-get org-roam-capture--info ksym)
(plist-get org-roam-capture--info ksym))
(t (let ((r (completing-read (format "%s: " key) nil nil nil default-val)))
(plist-put org-roam-capture--info ksym r)
r))))))))
(defun org-roam-capture--convert-template (template &optional props)
"Convert TEMPLATE from Org-roam syntax to `org-capture-templates' syntax.
PROPS is a plist containing additional Org-roam specific
properties to be added to the template."
(pcase template
(`(,_key ,_desc)
template)
((or `(,key ,desc ,type ignore ,body . ,rest)
`(,key ,desc ,type (function ignore) ,body . ,rest)
`(,key ,desc ,type ,body . ,rest))
(setq rest (append rest props))
(let (org-roam-plist options)
(while rest
(let* ((key (pop rest))
(val (pop rest))
(custom (member key org-roam-capture--template-keywords)))
(when (and custom
(not val))
(user-error "Invalid capture template format: %s\nkey %s cannot be nil" template key))
(if custom
(setq org-roam-plist (plist-put org-roam-plist key val))
(setq options (plist-put options key val)))))
(append `(,key ,desc ,type #'org-roam-capture--prepare-buffer ,body)
options
(list :org-roam org-roam-plist))))
(_
(signal 'invalid-template template))))
(provide 'org-roam-capture)
;;; org-roam-capture.el ends here

207
org-roam-compat.el Normal file
View File

@ -0,0 +1,207 @@
;;; org-roam-compat.el --- Backward compatibility code -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This file is dedicated to maintain backward compatibility with older older
;; Emacsen and Org-roam versions.
;;
;;; Code:
;;; Backports
;; REVIEW Remove when 26.x support is dropped. This is exact the same as
;; `directory-files-recursively' from Emacs 26, but with FOLLOW-SYMLINKS
;; parameter from Emacs 27.
(defun org-roam--directory-files-recursively (dir regexp
&optional include-directories predicate
follow-symlinks)
"Return list of all files under directory DIR whose names match REGEXP.
This function works recursively. Files are returned in \"depth
first\" order, and files from each directory are sorted in
alphabetical order. Each file name appears in the returned list
in its absolute form.
By default, the returned list excludes directories, but if
optional argument INCLUDE-DIRECTORIES is non-nil, they are
included.
PREDICATE can be either nil (which means that all subdirectories
of DIR are descended into), t (which means that subdirectories that
can't be read are ignored), or a function (which is called with
the name of each subdirectory, and should return non-nil if the
subdirectory is to be descended into).
If FOLLOW-SYMLINKS is non-nil, symbolic links that point to
directories are followed. Note that this can lead to infinite
recursion."
(let* ((result nil)
(files nil)
(dir (directory-file-name dir))
;; When DIR is "/", remote file names like "/method:" could
;; also be offered. We shall suppress them.
(tramp-mode (and tramp-mode (file-remote-p (expand-file-name dir)))))
(dolist (file (sort (file-name-all-completions "" dir)
'string<))
(unless (member file '("./" "../"))
(if (directory-name-p file)
(let* ((leaf (substring file 0 (1- (length file))))
(full-file (concat dir "/" leaf)))
;; Don't follow symlinks to other directories.
(when (and (or (not (file-symlink-p full-file))
(and (file-symlink-p full-file)
follow-symlinks))
;; Allow filtering subdirectories.
(or (eq predicate nil)
(eq predicate t)
(funcall predicate full-file)))
(let ((sub-files
(if (eq predicate t)
(condition-case nil
(org-roam--directory-files-recursively
full-file regexp include-directories
predicate follow-symlinks)
(file-error nil))
(org-roam--directory-files-recursively
full-file regexp include-directories
predicate follow-symlinks))))
(setq result (nconc result sub-files))))
(when (and include-directories
(string-match regexp leaf))
(setq result (nconc result (list full-file)))))
(when (string-match regexp file)
(push (concat dir "/" file) files)))))
(nconc result (nreverse files))))
;;; Compatibility hacks and patches
(advice-add #'org-id-add-location :around #'org-roam--handle-absent-org-id-locations-file-a)
(defun org-roam--handle-absent-org-id-locations-file-a (fn &rest args)
"Gracefully handle errors related to absence of `org-id-locations-file'.
FN is `org-id-locations-file' that comes from advice and ARGS are
passed to it."
(let (result)
;; Use `unwind-protect' over `condition-case' because `org-id' can produce various other errors, but all
;; of its errors are generic ones, so trapping all of them isn't a good idea and preserving the correct
;; backtrace is valuable.
(unwind-protect (setq result (apply fn args))
(unless result
(unless org-id-locations
;; Pre-allocate the hash table to avoid weird access related errors during the regeneration.
(setq org-id-locations (make-hash-table :type 'equal)))
;; `org-id' makes the assumption that `org-id-locations-file' will be stored in `user-emacs-directory'
;; which always exist if you have Emacs, so it uses `with-temp-file' to write to the file. However,
;; the users *do* change the path to this file and `with-temp-file' unable to create the file, if the
;; path to it consists of directories that don't exist. We'll have to handle this ourselves.
(unless (file-exists-p (file-truename org-id-locations-file))
;; If permissions allow that, try to create the user specified directory path to
;; `org-id-locations-file' ourselves.
(condition-case _err
(progn (org-roam-message (concat "`org-id-locations-file' (%s) doesn't exist. "
"Trying to regenerate it (this may take a while)...")
org-id-locations-file)
(make-directory (file-name-directory (file-truename org-id-locations-file)))
(org-roam-update-org-id-locations)
(apply fn args))
;; In case of failure (lack of permissions), we'll patch it to at least handle the current session
;; without errors.
(file-error (org-roam-message "Failed to regenerate `org-id-locations-file'")
(lwarn 'org-roam :error "
--------
WARNING: `org-id-locations-file' (%s) doesn't exist!
Org-roam is unable to create it for you.
--------
This happens when Emacs doesn't have permissions to create the
path to your `org-id-locations-file'. Org-roam will now fallback
storing the file in your current `org-roam-directory', but the
warning will keep popup with each new session.
To stop this warning from popping up, set `org-id-locations-file'
to the location you want and ensure that the path exists on your
filesystem, then run M-x `org-roam-update-org-id-locations'.
Note: While Org-roam doesn't depend on `org-id-locations-file' to
lookup IDs for the nodes that are stored in the database, it
still tries to keep it updated so IDs work across other files in
Org-mode, so the IDs used in your `org-roam-directory' would be
able to cross-reference outside of `org-roam-directory'. It also
allows to keep linking with \"id:\" links within the current
`org-roam-directory' to headings and files that are excluded from
identification (e.g. with \"ROAM_EXCLUDE\" property) as Org-roam
nodes." org-id-locations-file)
(setq org-id-locations-file
(expand-file-name ".orgids" (file-truename org-roam-directory)))
(apply fn args)))))
result)))
;;; Obsolete aliases (remove after next major release)
(define-obsolete-function-alias
'org-roam-setup
'org-roam-db-autosync-enable "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-teardown
'org-roam-db-autosync-disable "org-roam 2.0")
(define-obsolete-variable-alias
'org-roam-current-node
'org-roam-buffer-current-node "org-roam 2.0")
(define-obsolete-variable-alias
'org-roam-current-directory
'org-roam-buffer-current-directory "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-buffer-render
'org-roam-buffer-render-contents "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-buffer
'org-roam-buffer-display-dedicated "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-visit-thing
'org-roam-buffer-visit-thing "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-today
'org-roam-dailies-goto-today "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-yesterday
'org-roam-dailies-goto-yesterday "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-tomorrow
'org-roam-dailies-goto-tomorrow "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-next-note
'org-roam-dailies-goto-next-note "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-previous-note
'org-roam-dailies-goto-previous-note "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-date
'org-roam-dailies-goto-date "org-roam 2.0")
;;; Obsolete functions
(make-obsolete 'org-roam-get-keyword 'org-collect-keywords "org-roam 2.0")
(provide 'org-roam-compat)
;;; org-roam-compat.el ends here

621
org-roam-db.el Normal file
View File

@ -0,0 +1,621 @@
;;; org-roam-db.el --- Org-roam database API -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This module provides the underlying database API to Org-roam.
;;
;;; Code:
(require 'org-roam)
(defvar org-outline-path-cache)
;;; Options
(defcustom org-roam-db-location (expand-file-name "org-roam.db" user-emacs-directory)
"The path to file where the Org-roam database is stored.
It is the user's responsibility to set this correctly, especially
when used with multiple Org-roam instances."
:type 'string
:group 'org-roam)
(defcustom org-roam-db-gc-threshold gc-cons-threshold
"The value to temporarily set the `gc-cons-threshold' threshold to.
During `org-roam-db-sync', Emacs can pause multiple times to
perform garbage collection because of the large number of
temporary structures generated (e.g. parsed ASTs).
`gc-cons-threshold' is temporarily set to
`org-roam-db-gc-threshold' during this operation, and increasing
`gc-cons-threshold' will help reduce the number of GC operations,
at the cost of memory usage. Tweaking this value may lead to
better overall performance.
For example, to reduce the number of GCs to the minimum, on
machines with large memory one may set it to
`most-positive-fixnum'."
:type 'int
:group 'org-roam)
(defcustom org-roam-db-node-include-function (lambda () t)
"A custom function to check if the point contains a valid node.
This function is called each time a node (both file and headline)
is about to be saved into the Org-roam database.
If the function returns nil, Org-roam will skip the node. This
function is useful for excluding certain nodes from the Org-roam
database."
:type 'function
:group 'org-roam)
(defcustom org-roam-db-update-on-save t
"If t, update the Org-roam database upon saving the file.
Disable this if your files are large and updating the database is
slow."
:type 'boolean
:group 'org-roam)
;;; Variables
(defconst org-roam-db-version 16)
;; TODO Rename this
(defconst org-roam--sqlite-available-p
(with-demoted-errors "Org-roam initialization: %S"
(emacsql-sqlite-ensure-binary)
t))
(defvar org-roam-db--connection (make-hash-table :test #'equal)
"Database connection to Org-roam database.")
;;; Core Functions
(defun org-roam-db--get-connection ()
"Return the database connection, if any."
(gethash (expand-file-name org-roam-directory)
org-roam-db--connection))
(defun org-roam-db ()
"Entrypoint to the Org-roam sqlite database.
Initializes and stores the database, and the database connection.
Performs a database upgrade when required."
(unless (and (org-roam-db--get-connection)
(emacsql-live-p (org-roam-db--get-connection)))
(let ((init-db (not (file-exists-p org-roam-db-location))))
(make-directory (file-name-directory org-roam-db-location) t)
(let ((conn (emacsql-sqlite org-roam-db-location)))
(set-process-query-on-exit-flag (emacsql-process conn) nil)
(puthash (expand-file-name org-roam-directory)
conn
org-roam-db--connection)
(when init-db
(org-roam-db--init conn))
(let* ((version (caar (emacsql conn "PRAGMA user_version")))
(version (org-roam-db--upgrade-maybe conn version)))
(cond
((> version org-roam-db-version)
(emacsql-close conn)
(user-error
"The Org-roam database was created with a newer Org-roam version. "
"You need to update the Org-roam package"))
((< version org-roam-db-version)
(emacsql-close conn)
(error "BUG: The Org-roam database scheme changed %s"
"and there is no upgrade path")))))))
(org-roam-db--get-connection))
;;; Entrypoint: (org-roam-db-query)
(define-error 'emacsql-constraint "SQL constraint violation")
(defun org-roam-db-query (sql &rest args)
"Run SQL query on Org-roam database with ARGS.
SQL can be either the emacsql vector representation, or a string."
(apply #'emacsql (org-roam-db) sql args))
(defun org-roam-db-query! (handler sql &rest args)
"Run SQL query on Org-roam database with ARGS.
SQL can be either the emacsql vector representation, or a string.
The query is expected to be able to fail, in this situation, run HANDLER."
(condition-case err
(org-roam-db-query sql args)
(emacsql-constraint
(funcall handler err))))
;;; Schemata
(defconst org-roam-db--table-schemata
'((files
[(file :unique :primary-key)
(hash :not-null)
(atime :not-null)
(mtime :not-null)])
(nodes
([(id :not-null :primary-key)
(file :not-null)
(level :not-null)
(pos :not-null)
todo
priority
(scheduled text)
(deadline text)
title
properties
olp]
(:foreign-key [file] :references files [file] :on-delete :cascade)))
(aliases
([(node-id :not-null)
alias]
(:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
(refs
([(node-id :not-null)
(ref :not-null)
(type :not-null)]
(:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
(tags
([(node-id :not-null)
tag]
(:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
(links
([(pos :not-null)
(source :not-null)
(dest :not-null)
(type :not-null)
(properties :not-null)]
(:foreign-key [source] :references nodes [id] :on-delete :cascade)))))
(defconst org-roam-db--table-indices
'((alias-node-id aliases [node-id])
(refs-node-id refs [node-id])
(tags-node-id tags [node-id])))
(defun org-roam-db--init (db)
"Initialize database DB with the correct schema and user version."
(emacsql-with-transaction db
(emacsql db "PRAGMA foreign_keys = ON")
(pcase-dolist (`(,table ,schema) org-roam-db--table-schemata)
(emacsql db [:create-table $i1 $S2] table schema))
(pcase-dolist (`(,index-name ,table ,columns) org-roam-db--table-indices)
(emacsql db [:create-index $i1 :on $i2 $S3] index-name table columns))
(emacsql db (format "PRAGMA user_version = %s" org-roam-db-version))))
(defun org-roam-db--upgrade-maybe (db version)
"Upgrades the database schema for DB, if VERSION is old."
(emacsql-with-transaction db
'ignore
(if (< version org-roam-db-version)
(progn
(org-roam-message (format "Upgrading the Org-roam database from version %d to version %d"
version org-roam-db-version))
(org-roam-db-sync t))))
version)
(defun org-roam-db--close (&optional db)
"Closes the database connection for database DB.
If DB is nil, closes the database connection for the database in
the current `org-roam-directory'."
(unless db
(setq db (org-roam-db--get-connection)))
(when (and db (emacsql-live-p db))
(emacsql-close db)))
(defun org-roam-db--close-all ()
"Closes all database connections made by Org-roam."
(dolist (conn (hash-table-values org-roam-db--connection))
(org-roam-db--close conn)))
;;; Database API
;;;; Clearing
(defun org-roam-db-clear-all ()
"Clears all entries in the Org-roam cache."
(interactive)
(when (file-exists-p org-roam-db-location)
(dolist (table (mapcar #'car org-roam-db--table-schemata))
(org-roam-db-query `[:delete :from ,table]))))
(defun org-roam-db-clear-file (&optional file)
"Remove any related links to the FILE.
This is equivalent to removing the node from the graph.
If FILE is nil, clear the current buffer."
(setq file (or file (buffer-file-name (buffer-base-buffer))))
(org-roam-db-query [:delete :from files
:where (= file $s1)]
file))
;;;; Updating tables
(defun org-roam-db-insert-file ()
"Update the files table for the current buffer.
If UPDATE-P is non-nil, first remove the file in the database."
(let* ((file (buffer-file-name))
(attr (file-attributes file))
(atime (file-attribute-access-time attr))
(mtime (file-attribute-modification-time attr))
(hash (org-roam-db--file-hash)))
(org-roam-db-query
[:insert :into files
:values $v1]
(list (vector file hash atime mtime)))))
(defun org-roam-db-get-scheduled-time ()
"Return the scheduled time at point in ISO8601 format."
(when-let ((time (org-get-scheduled-time (point))))
(org-format-time-string "%FT%T%z" time)))
(defun org-roam-db-get-deadline-time ()
"Return the deadline time at point in ISO8601 format."
(when-let ((time (org-get-deadline-time (point))))
(org-format-time-string "%FT%T%z" time)))
(defun org-roam-db-node-p ()
"Return t if headline at point is an Org-roam node, else return nil."
(and (org-id-get)
(not (cdr (assoc "ROAM_EXCLUDE" (org-entry-properties))))
(funcall org-roam-db-node-include-function)))
(defun org-roam-db-map-nodes (fns)
"Run FNS over all nodes in the current buffer."
(org-with-point-at 1
(org-map-entries
(lambda ()
(when (org-roam-db-node-p)
(dolist (fn fns)
(funcall fn)))))))
(defun org-roam-db-map-links (fns)
"Run FNS over all links in the current buffer."
(org-with-point-at 1
(org-element-map (org-element-parse-buffer) 'link
(lambda (link)
(dolist (fn fns)
(funcall fn link))))))
(defun org-roam-db-insert-file-node ()
"Insert the file-level node into the Org-roam cache."
(org-with-point-at 1
(when (and (= (org-outline-level) 0)
(org-roam-db-node-p))
(when-let ((id (org-id-get)))
(let* ((file (buffer-file-name (buffer-base-buffer)))
(title (org-link-display-format
(or (cadr (assoc "TITLE" (org-collect-keywords '("title"))
#'string-equal))
(file-relative-name file org-roam-directory))))
(pos (point))
(todo nil)
(priority nil)
(scheduled nil)
(deadline nil)
(level 0)
(aliases (org-entry-get (point) "ROAM_ALIASES"))
(tags org-file-tags)
(refs (org-entry-get (point) "ROAM_REFS"))
(properties (org-entry-properties))
(olp nil))
(org-roam-db-query!
(lambda (err)
(lwarn 'org-roam :warning "%s for %s (%s) in %s"
(error-message-string err)
title id file))
[:insert :into nodes
:values $v1]
(vector id file level pos todo priority
scheduled deadline title properties olp))
(when tags
(org-roam-db-query
[:insert :into tags
:values $v1]
(mapcar (lambda (tag)
(vector id (substring-no-properties tag)))
tags)))
(when aliases
(org-roam-db-query
[:insert :into aliases
:values $v1]
(mapcar (lambda (alias)
(vector id alias))
(split-string-and-unquote aliases))))
(when refs
(setq refs (split-string-and-unquote refs))
(let (rows)
(dolist (ref refs)
(if (string-match org-link-plain-re ref)
(progn
(push (vector id (match-string 2 ref)
(match-string 1 ref)) rows))
(lwarn '(org-roam) :warning
"%s:%s\tInvalid ref %s, skipping..."
(buffer-file-name) (point) ref)))
(when rows
(org-roam-db-query
[:insert :into refs
:values $v1]
rows)))))))))
(cl-defun org-roam-db-insert-node-data ()
"Insert node data for headline at point into the Org-roam cache."
(when-let ((id (org-id-get)))
(let* ((file (buffer-file-name (buffer-base-buffer)))
(heading-components (org-heading-components))
(pos (point))
(todo (nth 2 heading-components))
(priority (nth 3 heading-components))
(level (nth 1 heading-components))
(scheduled (org-roam-db-get-scheduled-time))
(deadline (org-roam-db-get-deadline-time))
(title (or (nth 4 heading-components)
(progn (lwarn 'org-roam :warning "Node in %s:%s:%s has no title, skipping..."
file
(line-number-at-pos)
(1+ (- (point) (line-beginning-position))))
(cl-return-from org-roam-db-insert-node-data))))
(properties (org-entry-properties))
(olp (org-get-outline-path nil 'use-cache))
(title (org-link-display-format title)))
(org-roam-db-query!
(lambda (err)
(lwarn 'org-roam :warning "%s for %s (%s) in %s"
(error-message-string err)
title id file))
[:insert :into nodes
:values $v1]
(vector id file level pos todo priority
scheduled deadline title properties olp)))))
(defun org-roam-db-insert-aliases ()
"Insert aliases for node at point into Org-roam cache."
(when-let ((node-id (org-id-get))
(aliases (org-entry-get (point) "ROAM_ALIASES")))
(org-roam-db-query [:insert :into aliases
:values $v1]
(mapcar (lambda (alias)
(vector node-id alias))
(split-string-and-unquote aliases)))))
(defun org-roam-db-insert-tags ()
"Insert tags for node at point into Org-roam cache."
(when-let ((node-id (org-id-get))
(tags (org-get-tags)))
(org-roam-db-query [:insert :into tags
:values $v1]
(mapcar (lambda (tag)
(vector node-id (substring-no-properties tag))) tags))))
(defun org-roam-db-insert-refs ()
"Insert refs for node at point into Org-roam cache."
(when-let* ((node-id (org-id-get))
(refs (org-entry-get (point) "ROAM_REFS"))
(refs (split-string-and-unquote refs)))
(let (rows)
(dolist (ref refs)
(save-match-data
(if (string-match org-link-plain-re ref)
(progn
(push (vector node-id (match-string 2 ref) (match-string 1 ref)) rows))
(lwarn '(org-roam) :warning
"%s:%s\tInvalid ref %s, skipping..." (buffer-file-name) (point) ref))))
(org-roam-db-query [:insert :into refs
:values $v1]
rows))))
(defun org-roam-db-insert-link (link)
"Insert link data for LINK at current point into the Org-roam cache."
(save-excursion
(goto-char (org-element-property :begin link))
(let ((type (org-element-property :type link))
(path (org-element-property :path link))
(properties (list :outline (ignore-errors
;; This can error if link is not under any headline
(org-get-outline-path 'with-self 'use-cache))))
(source (org-roam-id-at-point)))
;; For Org-ref links, we need to split the path into the cite keys
(when (and (boundp 'org-ref-cite-types)
(fboundp 'org-ref-split-and-strip-string)
(member type org-ref-cite-types))
(setq path (org-ref-split-and-strip-string path)))
(unless (listp path)
(setq path (list path)))
(when (and source path)
(org-roam-db-query
[:insert :into links
:values $v1]
(mapcar (lambda (p)
(vector (point) source p type properties))
path))))))
;;;; Fetching
(defun org-roam-db--get-current-files ()
"Return a hash-table of file to the hash of its file contents."
(let ((current-files (org-roam-db-query [:select [file hash] :from files]))
(ht (make-hash-table :test #'equal)))
(dolist (row current-files)
(puthash (car row) (cadr row) ht))
ht))
(defun org-roam-db--file-hash (&optional file-path)
"Compute the hash of FILE-PATH, a file or current buffer."
;; If it is a GPG encrypted file, we always want to compute the hash
;; for the GPG encrypted file (undecrypted)
(when (and (not file-path) (equal "gpg" (file-name-extension (buffer-file-name))))
(setq file-path (buffer-file-name)))
(if file-path
(with-temp-buffer
(set-buffer-multibyte nil)
(insert-file-contents-literally file-path)
(secure-hash 'sha1 (current-buffer)))
(org-with-wide-buffer
(secure-hash 'sha1 (current-buffer)))))
;;;; Synchronization
(defun org-roam-db-update-file (&optional file-path)
"Update Org-roam cache for FILE-PATH.
If the file does not exist anymore, remove it from the cache.
If the file exists, update the cache with information."
(setq file-path (or file-path (buffer-file-name (buffer-base-buffer))))
(let ((content-hash (org-roam-db--file-hash file-path))
(db-hash (caar (org-roam-db-query [:select hash :from files
:where (= file $s1)] file-path))))
(unless (string= content-hash db-hash)
(org-roam-with-file file-path nil
(save-excursion
(org-set-regexps-and-options 'tags-only)
(org-roam-db-clear-file)
(org-roam-db-insert-file)
(org-roam-db-insert-file-node)
(setq org-outline-path-cache nil)
(org-roam-db-map-nodes
(list #'org-roam-db-insert-node-data
#'org-roam-db-insert-aliases
#'org-roam-db-insert-tags
#'org-roam-db-insert-refs))
(setq org-outline-path-cache nil)
(org-roam-db-map-links
(list #'org-roam-db-insert-link)))))))
;;;###autoload
(defun org-roam-db-sync (&optional force)
"Synchronize the cache state with the current Org files on-disk.
If FORCE, force a rebuild of the cache from scratch."
(interactive "P")
(org-roam-db--close) ;; Force a reconnect
(when force (delete-file org-roam-db-location))
(org-roam-db) ;; To initialize the database, no-op if already initialized
(let* ((gc-cons-threshold org-roam-db-gc-threshold)
(org-agenda-files nil)
(org-roam-files (org-roam-list-files))
(current-files (org-roam-db--get-current-files))
(modified-files nil))
(dolist (file org-roam-files)
(let ((contents-hash (org-roam-db--file-hash file)))
(unless (string= (gethash file current-files)
contents-hash)
(push file modified-files)))
(remhash file current-files))
(emacsql-with-transaction (org-roam-db)
(if (fboundp 'dolist-with-progress-reporter)
(dolist-with-progress-reporter (file (hash-table-keys current-files))
"Clearing removed files..."
(org-roam-db-clear-file file))
(dolist (file (hash-table-keys current-files))
(org-roam-db-clear-file file)))
(if (fboundp 'dolist-with-progress-reporter)
(dolist-with-progress-reporter (file modified-files)
"Processing modified files..."
(org-roam-db-update-file file))
(dolist (file modified-files)
(org-roam-db-update-file file))))))
;;;###autoload
(define-minor-mode org-roam-db-autosync-mode
"Global minor mode to keep your Org-roam session automatically synchronized.
Through the session this will continue to setup your
buffers (that are Org-roam file visiting), keep track of the
related changes, maintain cache consistency and incrementally
update the currently active database.
If you need to manually trigger resync of the currently active
database, see `org-roam-db-sync' command."
:group 'org-roam
:global t
:init-value nil
(let ((enabled org-roam-db-autosync-mode))
(cond
(enabled
(add-hook 'find-file-hook #'org-roam-db-autosync--setup-file-h)
(add-hook 'kill-emacs-hook #'org-roam-db--close-all)
(advice-add #'rename-file :after #'org-roam-db-autosync--rename-file-a)
(advice-add #'delete-file :before #'org-roam-db-autosync--delete-file-a)
(org-roam-db-sync))
(t
(remove-hook 'find-file-hook #'org-roam-db-autosync--setup-file-h)
(remove-hook 'kill-emacs-hook #'org-roam-db--close-all)
(advice-remove #'rename-file #'org-roam-db-autosync--rename-file-a)
(advice-remove #'delete-file #'org-roam-db-autosync--delete-file-a)
(org-roam-db--close-all)
;; Disable local hooks for all org-roam buffers
(dolist (buf (org-roam-buffer-list))
(with-current-buffer buf
(remove-hook 'after-save-hook #'org-roam-db-autosync--try-update-on-save-h t)))))))
;;;###autoload
(defun org-roam-db-autosync-enable ()
"Activate `org-roam-db-autosync-mode'."
(org-roam-db-autosync-mode +1))
(defun org-roam-db-autosync-disable ()
"Deactivate `org-roam-db-autosync-mode'."
(org-roam-db-autosync-mode -1))
(defun org-roam-db-autosync-toggle ()
"Toggle `org-roam-db-autosync-mode' enabled/disabled."
(org-roam-db-autosync-mode 'toggle))
(defun org-roam-db-autosync--delete-file-a (file &optional _trash)
"Maintain cache consistency when file deletes.
FILE is removed from the database."
(when (and (not (auto-save-file-name-p file))
(not (backup-file-name-p file))
(org-roam-file-p file))
(org-roam-db-clear-file (expand-file-name file))))
(defun org-roam-db-autosync--rename-file-a (old-file new-file-or-dir &rest _args)
"Maintain cache consistency of file rename.
OLD-FILE is cleared from the database, and NEW-FILE-OR-DIR is added."
(let ((new-file (if (directory-name-p new-file-or-dir)
(expand-file-name (file-name-nondirectory old-file) new-file-or-dir)
new-file-or-dir)))
(setq new-file (expand-file-name new-file))
(setq old-file (expand-file-name old-file))
(when (and (not (auto-save-file-name-p old-file))
(not (auto-save-file-name-p new-file))
(not (backup-file-name-p old-file))
(not (backup-file-name-p new-file))
(org-roam-file-p old-file))
(org-roam-db-clear-file old-file))
(when (org-roam-file-p new-file)
(org-roam-db-update-file new-file))))
(defun org-roam-db-autosync--setup-file-h ()
"Setup the current buffer if it visits an Org-roam file."
(when (org-roam-file-p) (run-hooks 'org-roam-find-file-hook)))
(add-hook 'org-roam-find-file-hook #'org-roam-db-autosync--setup-update-on-save-h)
(defun org-roam-db-autosync--setup-update-on-save-h ()
"Setup the current buffer to update the DB after saving the current file."
(add-hook 'after-save-hook #'org-roam-db-autosync--try-update-on-save-h nil t))
(defun org-roam-db-autosync--try-update-on-save-h ()
"If appropriate, update the database for the current file after saving buffer."
(when org-roam-db-update-on-save (org-roam-db-update-file)))
;;; Diagnostics
(defun org-roam-db-diagnose-node ()
"Print information about node at point."
(interactive)
(prin1 (org-roam-node-at-point)))
(provide 'org-roam-db)
;;; org-roam-db.el ends here

210
org-roam-migrate.el Normal file
View File

@ -0,0 +1,210 @@
;;; org-roam-migrate.el --- Migration utilities from v1 to v2 -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This is a special library provided for the v1 users of this package. It's
;; purpose is to ease the transition from v1 to v2, by providing migration
;; utilities to convert from v1 notes to v2 nodes.
;;
;;; Code:
(require 'org-roam)
;;; v1 breaking warning
(defvar org-roam-v2-ack nil
"When set to t, won't display the annoying warning message about the upgrade.
Need to be set before the package is loaded, otherwise won't take
any affect.")
(unless org-roam-v2-ack
(lwarn 'org-roam :error "
------------------------------------
WARNING: You're now on Org-roam v2!
------------------------------------
You may have arrived here from a package upgrade. Please read the
wiki entry at
%s
for an overview of the major changes.
Notes taken in v1 are incompatible with v2, but you can upgrade
them to the v2 format via a simple command. To migrate your
notes, first make sure you're on at least Org 9.4 (check with
C-h v org-version) and set your org-roam-directory to your notes:
(setq org-roam-directory \"path/to/org/files\")
then, run:
M-x org-roam-migrate-wizard
If you wish to stay on v1, v1 is unfortunately not distributed on
MELPA. See org-roam/org-roam-v1 on GitHub on how to install v1.
If you've gone through the migration steps (if necessary), and
know what you're doing set `org-roam-v2-ack' to `t' to disable
this warning. You can do so by adding:
(setq org-roam-v2-ack t)
To your init file.
"
"https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2"))
;;; Migration wizard (v1 -> v2)
;;;###autoload
(defun org-roam-migrate-wizard ()
"Migrate all notes from to be compatible with Org-roam v2.
1. Convert all notes from v1 format to v2.
2. Rebuild the cache.
3. Replace all file links with ID links."
(interactive)
(when (yes-or-no-p "Org-roam will now convert all your notes from v1 to v2.
This will take a while. Are you sure you want to do this?")
;; Back up notes
(let ((backup-dir (expand-file-name "org-roam.bak"
(file-name-directory (directory-file-name org-roam-directory)))))
(message "Backing up files to %s" backup-dir)
(copy-directory org-roam-directory backup-dir))
;; Upgrade database to v2
(org-roam-db-sync 'force)
;; Convert v1 to v2
(dolist (f (org-roam-list-files))
(org-roam-with-file f nil
(org-roam-migrate-v1-to-v2)))
;; Rebuild cache
(org-roam-db-sync 'force)
;;Replace all file links with ID links
(dolist (f (org-roam-list-files))
(org-roam-with-file f nil
(org-roam-migrate-replace-file-links-with-id)
(save-buffer)))))
(defun org-roam-migrate-v1-to-v2 ()
"Convert the current buffer to v2 format."
;; Create file level ID
(org-with-point-at 1
(org-id-get-create))
;; Replace roam_key into properties drawer roam_ref
(when-let* ((refs (mapcan #'split-string-and-unquote
(cdar (org-collect-keywords '("roam_key"))))))
(let ((case-fold-search t))
(org-with-point-at 1
(dolist (ref refs)
(org-roam-ref-add ref))
(while (re-search-forward "^#\\+roam_key:" (point-max) t)
(beginning-of-line)
(kill-line 1)))))
;; Replace roam_alias into properties drawer roam_aliases
(when-let* ((aliases (mapcan #'split-string-and-unquote
(cdar (org-collect-keywords '("roam_alias"))))))
(dolist (alias aliases)
(org-roam-alias-add alias)))
(let ((case-fold-search t))
(org-with-point-at 1
(while (re-search-forward "^#\\+roam_alias:" (point-max) t)
(beginning-of-line)
(kill-line 1))))
;; Replace #+roam_tags into #+filetags
(org-with-point-at 1
(let* ((roam-tags (org-roam-migrate-get-prop-list "ROAM_TAGS"))
(file-tags (cl-mapcan (lambda (value)
(cl-mapcan
(lambda (k) (org-split-string k ":"))
(split-string value)))
(org-roam-migrate-get-prop-list "FILETAGS")))
(tags (append roam-tags file-tags))
(tags (seq-map (lambda (tag)
(replace-regexp-in-string
"[^[:alnum:]_@#%]"
"_"
tag)) tags))
(tags (seq-uniq tags)))
(when tags
(org-roam-migrate-prop-set "filetags" (org-make-tag-string tags))))
(let ((case-fold-search t))
(org-with-point-at 1
(while (re-search-forward "^#\\+roam_tags:" (point-max) t)
(beginning-of-line)
(kill-line 1)))))
(save-buffer))
(defun org-roam-migrate-get-prop-list (keyword)
"Return prop list for KEYWORD."
(let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase keyword)))
lst)
(goto-char (point-min))
(while (re-search-forward re 2048 t)
(setq lst (append lst (split-string-and-unquote
(buffer-substring-no-properties
(match-beginning 1) (match-end 1))))))
lst))
(defun org-roam-migrate-prop-set (name value)
"Set a file property called NAME to VALUE in buffer file.
If the property is already set, replace its value."
(setq name (downcase name))
(org-with-point-at 1
(let ((case-fold-search t))
(if (re-search-forward (concat "^#\\+" name ":\\(.*\\)")
(point-max) t)
(replace-match (concat "#+" name ": " value) 'fixedcase)
(while (and (not (eobp))
(looking-at "^[#:]"))
(if (save-excursion (end-of-line) (eobp))
(progn
(end-of-line)
(insert "\n"))
(forward-line)
(beginning-of-line)))
(insert "#+" name ": " value "\n")))))
(defun org-roam-migrate-replace-file-links-with-id ()
"Replace all file: links with ID links in current buffer."
(org-with-point-at 1
(while (re-search-forward org-link-bracket-re nil t)
(let* ((mdata (match-data))
(path (match-string 1))
(desc (match-string 2)))
(when (string-prefix-p "file:" path)
(setq path (expand-file-name (substring path 5)))
(when-let ((node-id (caar (org-roam-db-query [:select [id] :from nodes
:where (= file $s1)
:and (= level 0)] path))))
(set-match-data mdata)
(replace-match (org-link-make-string (concat "id:" node-id)
desc) nil t)))))))
(provide 'org-roam-migrate)
;;; org-roam-migrate.el ends here

691
org-roam-mode.el Normal file
View File

@ -0,0 +1,691 @@
;;; org-roam-mode.el --- Major mode for special Org-roam buffers -*- lexical-binding: t -*-
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
;; This module implements `org-roam-mode', which is a major mode that used by
;; special Org-roam buffers to display various content in a section-like manner
;; about the nodes and relevant to them information (e.g. backlinks) with which
;; the user can interact with.
;;
;;; Code:
(require 'org-roam)
;;;; Declarations
(defvar org-ref-buffer-hacked)
;;; Options
(defcustom org-roam-mode-section-functions (list #'org-roam-backlinks-section
#'org-roam-reflinks-section)
"Functions that insert sections in the `org-roam-mode' based buffers.
Each function is called with one argument, which is an
`org-roam-node' for which the buffer will be constructed for.
Normally this node is `org-roam-buffer-current-node'."
:group 'org-roam
:type 'hook)
;;; Faces
(defface org-roam-header-line
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:foreground "DarkGoldenrod4"
:weight bold)
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:foreground "LightGoldenrod2"
:weight bold))
"Face for the `header-line' in some Org-roam modes."
:group 'org-roam-faces)
(defface org-roam-title
'((t :weight bold))
"Face for Org-roam titles."
:group 'org-roam-faces)
(defface org-roam-olp
'((((class color) (background light)) :foreground "grey60")
(((class color) (background dark)) :foreground "grey40"))
"Face for the OLP of the node."
:group 'org-roam-faces)
(defface org-roam-preview-heading
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey80"
:foreground "grey30")
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey25"
:foreground "grey70"))
"Face for preview headings."
:group 'org-roam-faces)
(defface org-roam-preview-heading-highlight
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey75"
:foreground "grey30")
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey35"
:foreground "grey70"))
"Face for current preview headings."
:group 'org-roam-faces)
(defface org-roam-preview-heading-selection
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:inherit org-roam-preview-heading-highlight
:foreground "salmon4")
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:inherit org-roam-preview-heading-highlight
:foreground "LightSalmon3"))
"Face for selected preview headings."
:group 'org-roam-faces)
(defface org-roam-preview-region
`((t :inherit bold
,@(and (>= emacs-major-version 27)
(list :extend (ignore-errors (face-attribute 'region :extend))))))
"Face used by `org-roam-highlight-preview-region-using-face'.
This face is overlaid over text that uses other hunk faces,
and those normally set the foreground and background colors.
The `:foreground' and especially the `:background' properties
should be avoided here. Setting the latter would cause the
loss of information. Good properties to set here are `:weight'
and `:slant'."
:group 'org-roam-faces)
(defface org-roam-dim
'((((class color) (background light)) :foreground "grey60")
(((class color) (background dark)) :foreground "grey40"))
"Face for the dimmer part of the widgets."
:group 'org-roam-faces)
;;; Major mode
(defvar org-roam-mode-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map magit-section-mode-map)
(define-key map [C-return] 'org-roam-buffer-visit-thing)
(define-key map (kbd "C-m") 'org-roam-buffer-visit-thing)
(define-key map [remap revert-buffer] 'org-roam-buffer-refresh)
map)
"Parent keymap for all keymaps of modes derived from `org-roam-mode'.")
(define-derived-mode org-roam-mode magit-section-mode "Org-roam"
"Major mode for displaying relevant information about Org-roam nodes.
This mode is used by special Org-roam buffers, such as persistent
`org-roam-buffer' and dedicated Org-roam buffers
\(`org-roam-buffer-display-dedicated'), which render the
information in a section-like manner (see
`org-roam-mode-section-functions'), with which the user can
interact with."
:group 'org-roam
(face-remap-add-relative 'header-line 'org-roam-header-line))
;;; Buffers
(defvar org-roam-buffer-current-node nil
"The node for which an `org-roam-mode' based buffer displays its contents.
This set both, locally and globally. Normally the local value is
only set in the `org-roam-mode' based buffers, while the global
value shows the current node in the persistent `org-roam-buffer'.")
(put 'org-roam-buffer-current-node 'permanent-local t)
(defvar org-roam-buffer-current-directory nil
"The `org-roam-directory' value of `org-roam-buffer-current-node'.
Set both, locally and globally in the same way as `org-roam-buffer-current-node'.")
(put 'org-roam-buffer-current-directory 'permanent-local t)
;;;; Library
(defun org-roam-buffer-visit-thing ()
"This is a placeholder command.
Where applicable, section-specific keymaps bind another command
which visits the thing at point."
(interactive)
(user-error "There is no thing at point that could be visited"))
(defun org-roam-buffer-file-at-point (&optional assert)
"Return the file at point in the current `org-roam-mode' based buffer.
If ASSERT, throw an error."
(if-let ((file (magit-section-case
(org-roam-node-section (org-roam-node-file (oref it node)))
(org-roam-grep-section (oref it file))
(org-roam-preview-section (oref it file))
(t (cl-assert (derived-mode-p 'org-roam-mode))))))
file
(when assert
(user-error "No file at point"))))
(defun org-roam-buffer-refresh ()
"Refresh the contents of the currently selected Org-roam buffer."
(interactive)
(cl-assert (derived-mode-p 'org-roam-mode))
(save-excursion (org-roam-buffer-render-contents)))
(defun org-roam-buffer-render-contents ()
"Recompute and render the contents of an Org-roam buffer.
Assumes that the current buffer is an `org-roam-mode' based
buffer."
(let ((inhibit-read-only t))
(erase-buffer)
(org-roam-mode)
(setq-local default-directory org-roam-buffer-current-directory)
(setq-local org-roam-directory org-roam-buffer-current-directory)
(org-roam-buffer-set-header-line-format
(org-roam-node-title org-roam-buffer-current-node))
(magit-insert-section (org-roam)
(magit-insert-heading)
(run-hook-with-args 'org-roam-mode-section-functions org-roam-buffer-current-node))
(goto-char 0)))
(defun org-roam-buffer-set-header-line-format (string)
"Set the header-line using STRING.
If the `face' property of any part of STRING is already set, then
that takes precedence. Also pad the left side of STRING so that
it aligns with the text area."
(setq-local header-line-format
(concat (propertize " " 'display '(space :align-to 0))
string)))
;;;; Dedicated buffer
;;;###autoload
(defun org-roam-buffer-display-dedicated (node)
"Launch NODE dedicated Org-roam buffer.
Unlike the persistent `org-roam-buffer', the contents of this
buffer won't be automatically changed and will be held in place.
In interactive calls prompt to select NODE, unless called with
`universal-argument', in which case NODE will be set to
`org-roam-node-at-point'."
(interactive
(list (if current-prefix-arg
(org-roam-node-at-point 'assert)
(org-roam-node-read nil nil nil 'require-match))))
(let ((buffer (get-buffer-create (org-roam-buffer--dedicated-name node))))
(with-current-buffer buffer
(setq-local org-roam-buffer-current-node node)
(setq-local org-roam-buffer-current-directory org-roam-directory)
(org-roam-buffer-render-contents))
(display-buffer buffer)))
(defun org-roam-buffer--dedicated-name (node)
"Construct buffer name for NODE dedicated Org-roam buffer."
(let ((title (org-roam-node-title node))
(filename (file-relative-name (org-roam-node-file node) org-roam-directory)))
(format "*org-roam: %s<%s>*" title filename)))
(defun org-roam-buffer-dedicated-p (&optional buffer)
"Return t if an Org-roam BUFFER is a node dedicated one.
See `org-roam-buffer-display-dedicated' for more details.
If BUFFER is nil, default it to `current-buffer'."
(or buffer (setq buffer (current-buffer)))
(string-match-p (concat "^" (regexp-quote "*org-roam: "))
(buffer-name buffer)))
;;;; Persistent buffer
(defvar org-roam-buffer "*org-roam*"
"The persistent Org-roam buffer name. Must be surround with \"*\".
The content inside of this buffer will be automatically updated
to the nearest node at point that comes from the current buffer.
To toggle its display use `org-roam-buffer-toggle' command.")
(defun org-roam-buffer-toggle ()
"Toggle display of the persistent `org-roam-buffer'."
(interactive)
(pcase (org-roam-buffer--visibility)
('visible
(progn
(delete-window (get-buffer-window org-roam-buffer))
(remove-hook 'post-command-hook #'org-roam-buffer--redisplay-h)))
((or 'exists 'none)
(progn
(display-buffer (get-buffer-create org-roam-buffer))
(org-roam-buffer-persistent-redisplay)))))
(define-inline org-roam-buffer--visibility ()
"Return the current visibility state of the persistent `org-roam-buffer'.
Valid states are 'visible, 'exists and 'none."
(declare (side-effect-free t))
(inline-quote
(cond
((get-buffer-window org-roam-buffer) 'visible)
((get-buffer org-roam-buffer) 'exists)
(t 'none))))
(defun org-roam-buffer-persistent-redisplay ()
"Recompute contents of the persistent `org-roam-buffer'.
Has no effect when there's no `org-roam-node-at-point'."
(when-let ((node (org-roam-node-at-point)))
(unless (equal node org-roam-buffer-current-node)
(setq org-roam-buffer-current-node node
org-roam-buffer-current-directory org-roam-directory)
(with-current-buffer (get-buffer-create org-roam-buffer)
(org-roam-buffer-render-contents)
(add-hook 'kill-buffer-hook #'org-roam-buffer--persistent-cleanup-h nil t)))))
(defun org-roam-buffer--persistent-cleanup-h ()
"Clean-up global state thats dedicated for the persistent `org-roam-buffer'."
(setq-default org-roam-buffer-current-node nil
org-roam-buffer-current-directory nil))
(add-hook 'org-roam-find-file-hook #'org-roam-buffer--setup-redisplay-h)
(defun org-roam-buffer--setup-redisplay-h ()
"Setup automatic redisplay of the persistent `org-roam-buffer'."
(add-hook 'post-command-hook #'org-roam-buffer--redisplay-h nil t))
(defun org-roam-buffer--redisplay-h ()
"Reconstruct the persistent `org-roam-buffer'.
This needs to be quick or infrequent, because this designed to
run at `post-command-hook'."
(and (get-buffer-window org-roam-buffer)
(org-roam-buffer-persistent-redisplay)))
;;; Sections
;;;; Node
(defvar org-roam-node-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map org-roam-mode-map)
(define-key map [remap org-roam-buffer-visit-thing] 'org-roam-node-visit)
map)
"Keymap for `org-roam-node-section's.")
(defclass org-roam-node-section (magit-section)
((keymap :initform 'org-roam-node-map)
(node :initform nil))
"A `magit-section' used by `org-roam-mode' to outline NODE in its own heading.")
(cl-defun org-roam-node-insert-section (&key source-node point properties)
"Insert section for a link from SOURCE-NODE to some other node.
The other node is normally `org-roam-buffer-current-node'.
SOURCE-NODE is an `org-roam-node' that links or references with
the other node.
POINT is a character position where the link is located in
SOURCE-NODE's file.
PROPERTIES (a plist) contains additional information about the
link.
Despite the name, this function actually inserts 2 sections at
the same time:
1. `org-roam-node-section' for a heading that describes
SOURCE-NODE. Acts as a parent section of the following one.
2. `org-roam-preview-section' for a preview content that comes
from SOURCE-NODE's file for the link (that references the
other node) at POINT. Acts a child section of the previous
one."
(unless (file-exists-p (org-roam-node-file source-node))
(cl-return-from org-roam-node-insert-section))
(magit-insert-section section (org-roam-node-section)
(let ((outline (if-let ((outline (plist-get properties :outline)))
(mapconcat #'org-link-display-format outline " > ")
"Top")))
(insert (concat (propertize (org-roam-node-title source-node)
'font-lock-face 'org-roam-title)
(format " (%s)"
(propertize outline 'font-lock-face 'org-roam-olp)))))
(magit-insert-heading)
(oset section node source-node)
(magit-insert-section section (org-roam-preview-section)
(insert (org-roam-fontify-like-in-org-mode
(org-roam-preview-get-contents (org-roam-node-file source-node) point))
"\n")
(oset section file (org-roam-node-file source-node))
(oset section point point)
(insert ?\n))))
;;;; Preview
(defvar org-roam-preview-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map org-roam-mode-map)
(define-key map [remap org-roam-buffer-visit-thing] 'org-roam-preview-visit)
map)
"Keymap for `org-roam-preview-section's.")
(defclass org-roam-preview-section (magit-section)
((keymap :initform 'org-roam-preview-map)
(file :initform nil)
(point :initform nil))
"A `magit-section' used by `org-roam-mode' to contain preview content.
The preview content comes from FILE, and the link as at POINT.")
(defun org-roam-preview-visit (file point &optional other-window)
"Visit FILE at POINT and return the visited buffer.
With OTHER-WINDOW non-nil do so in another window.
In interactive calls OTHER-WINDOW is set with
`universal-argument'."
(interactive (list (org-roam-buffer-file-at-point 'assert)
(oref (magit-current-section) point)
current-prefix-arg))
(let ((buf (find-file-noselect file))
(display-buffer-fn (if other-window
#'switch-to-buffer-other-window
#'pop-to-buffer-same-window)))
(funcall display-buffer-fn buf)
(with-current-buffer buf
(widen)
(goto-char point))
(when (org-invisible-p) (org-show-context))
buf))
(defun org-roam-preview-get-contents (file point)
"Get preview content for FILE at POINT."
(save-excursion
(org-roam-with-temp-buffer file
(goto-char point)
(let ((elem (org-element-at-point)))
;; We want the parent element always
(while (org-element-property :parent elem)
(setq elem (org-element-property :parent elem)))
(pcase (car elem)
('headline ; show subtree
(org-roam-preview-get-entry-text (point-marker) most-positive-fixnum))
(_
(let ((begin (org-element-property :begin elem))
(end (org-element-property :end elem)))
(or (string-trim (buffer-substring-no-properties begin end))
(org-element-property :raw-value elem)))))))))
(defun org-roam-preview-get-entry-text (marker n-lines &optional indent)
"Extract entry text from MARKER, at most N-LINES lines.
This will ignore drawers etc, just get the text.
If INDENT is given, prefix every line with this string."
(let (txt ind)
(save-excursion
(with-current-buffer (marker-buffer marker)
(if (not (derived-mode-p 'org-mode))
(setq txt "")
(org-with-wide-buffer
(goto-char marker)
(end-of-line 1)
(setq txt (buffer-substring
(min (1+ (point)) (point-max))
(progn (outline-next-heading) (point))))
(with-temp-buffer
(insert txt)
(goto-char (point-min))
(while (org-activate-links (point-max))
(goto-char (match-end 0)))
(goto-char (point-min))
(while (re-search-forward org-link-bracket-re (point-max) t)
(set-text-properties (match-beginning 0) (match-end 0)
nil))
(goto-char (point-min))
(while (re-search-forward org-drawer-regexp nil t)
(delete-region
(match-beginning 0)
(progn (re-search-forward
"^[ \t]*:END:.*\n?" nil 'move)
(point))))
(goto-char (point-min))
(goto-char (point-max))
(skip-chars-backward " \t\n")
(when (looking-at "[ \t\n]+\\'") (replace-match ""))
;; find and remove min common indentation
(goto-char (point-min))
(untabify (point-min) (point-max))
(setq ind (current-indentation))
(while (not (eobp))
(unless (looking-at "[ \t]*$")
(setq ind (min ind (current-indentation))))
(beginning-of-line 2))
(goto-char (point-min))
(while (not (eobp))
(unless (looking-at "[ \t]*$")
(move-to-column ind)
(delete-region (point-at-bol) (point)))
(beginning-of-line 2))
(goto-char (point-min))
(when indent
(while (and (not (eobp)) (re-search-forward "^" nil t))
(replace-match indent t t)))
(goto-char (point-min))
(while (looking-at "[ \t]*\n") (replace-match ""))
(goto-char (point-max))
(when (> (org-current-line)
n-lines)
(org-goto-line (1+ n-lines))
(backward-char 1))
(setq txt (buffer-substring (point-min) (point))))))))
txt))
;;;; Backlinks
(cl-defstruct (org-roam-backlink (:constructor org-roam-backlink-create)
(:copier nil))
source-node target-node
point properties)
(cl-defmethod org-roam-populate ((backlink org-roam-backlink))
"Populate BACKLINK from database."
(setf (org-roam-backlink-source-node backlink)
(org-roam-populate (org-roam-backlink-source-node backlink))
(org-roam-backlink-target-node backlink)
(org-roam-populate (org-roam-backlink-target-node backlink)))
backlink)
(defun org-roam-backlinks-get (node)
"Return the backlinks for NODE."
(let ((backlinks (org-roam-db-query
[:select [source dest pos properties]
:from links
:where (= dest $s1)
:and (= type "id")]
(org-roam-node-id node))))
(cl-loop for backlink in backlinks
collect (pcase-let ((`(,source-id ,dest-id ,pos ,properties) backlink))
(org-roam-populate
(org-roam-backlink-create
:source-node (org-roam-node-create :id source-id)
:target-node (org-roam-node-create :id dest-id)
:point pos
:properties properties))))))
(defun org-roam-backlinks-sort (a b)
"Default sorting function for backlinks A and B.
Sorts by title."
(string< (org-roam-node-title (org-roam-backlink-source-node a))
(org-roam-node-title (org-roam-backlink-source-node b))))
(defun org-roam-backlinks-section (node)
"The backlinks section for NODE."
(when-let ((backlinks (seq-sort #'org-roam-backlinks-sort (org-roam-backlinks-get node))))
(magit-insert-section (org-roam-backlinks)
(magit-insert-heading "Backlinks:")
(dolist (backlink backlinks)
(org-roam-node-insert-section
:source-node (org-roam-backlink-source-node backlink)
:point (org-roam-backlink-point backlink)
:properties (org-roam-backlink-properties backlink)))
(insert ?\n))))
;;;; Reflinks
(cl-defstruct (org-roam-reflink (:constructor org-roam-reflink-create)
(:copier nil))
source-node ref
point properties)
(cl-defmethod org-roam-populate ((reflink org-roam-reflink))
"Populate REFLINK from database."
(setf (org-roam-reflink-source-node reflink)
(org-roam-populate (org-roam-reflink-source-node reflink)))
reflink)
(defun org-roam-reflinks-get (node)
"Return the reflinks for NODE."
(let ((refs (org-roam-db-query [:select :distinct [refs:ref links:source links:pos links:properties]
:from refs
:left-join links
:where (= refs:node-id $s1)
:and (= links:dest refs:ref)]
(org-roam-node-id node)))
links)
(pcase-dolist (`(,ref ,source-id ,pos ,properties) refs)
(push (org-roam-populate
(org-roam-reflink-create
:source-node (org-roam-node-create :id source-id)
:ref ref
:point pos
:properties properties)) links))
links))
(defun org-roam-reflinks-sort (a b)
"Default sorting function for reflinks A and B.
Sorts by title."
(string< (org-roam-node-title (org-roam-reflink-source-node a))
(org-roam-node-title (org-roam-reflink-source-node b))))
(defun org-roam-reflinks-section (node)
"The reflinks section for NODE."
(when (org-roam-node-refs node)
(let* ((reflinks (seq-sort #'org-roam-reflinks-sort (org-roam-reflinks-get node))))
(magit-insert-section (org-roam-reflinks)
(magit-insert-heading "Reflinks:")
(dolist (reflink reflinks)
(org-roam-node-insert-section
:source-node (org-roam-reflink-source-node reflink)
:point (org-roam-reflink-point reflink)
:properties (org-roam-reflink-properties reflink)))
(insert ?\n)))))
;;;; Grep
(defvar org-roam-grep-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map org-roam-mode-map)
(define-key map [remap org-roam-buffer-visit-thing] 'org-roam-grep-visit)
map)
"Keymap for Org-roam grep result sections.")
(defclass org-roam-grep-section (magit-section)
((keymap :initform 'org-roam-grep-map)
(file :initform nil)
(row :initform nil)
(col :initform nil))
"A `magit-section' used by `org-roam-mode' to contain grep output.")
(defun org-roam-grep-visit (file &optional other-window row col)
"Visit FILE at row ROW (if any) and column COL (if any). Return the buffer.
With OTHER-WINDOW non-nil (in interactive calls set with
`universal-argument') display the buffer in another window
instead."
(interactive (list (org-roam-buffer-file-at-point t)
current-prefix-arg
(oref (magit-current-section) row)
(oref (magit-current-section) col)))
(let ((buf (find-file-noselect file))
(display-buffer-fn (if other-window
#'switch-to-buffer-other-window
#'pop-to-buffer-same-window)))
(funcall display-buffer-fn buf)
(with-current-buffer buf
(widen)
(goto-char (point-min))
(when row
(forward-line (1- row)))
(when col
(forward-char (1- col))))
(when (org-invisible-p) (org-show-context))
buf))
;;;; Unlinked references
(defvar org-roam-unlinked-references-result-re
(rx (group (one-or-more anything))
":"
(group (one-or-more digit))
":"
(group (one-or-more digit))
":"
(group (zero-or-more anything)))
"Regex for the return result of a ripgrep query.")
(defun org-roam-unlinked-references-preview-line (file row)
"Return the preview line from FILE.
This is the ROW within FILE."
(with-temp-buffer
(insert-file-contents file)
(forward-line (1- row))
(buffer-substring-no-properties
(save-excursion
(beginning-of-line)
(point))
(save-excursion
(end-of-line)
(point)))))
(defun org-roam-unlinked-references-section (node)
"The unlinked references section for NODE.
References from FILE are excluded."
(when (and (executable-find "rg")
(not (string-match "PCRE2 is not available"
(shell-command-to-string "rg --pcre2-version"))))
(let* ((titles (cons (org-roam-node-title node)
(org-roam-node-aliases node)))
(rg-command (concat "rg -o --vimgrep -P -i "
(mapconcat (lambda (glob) (concat "-g " glob))
(org-roam--list-files-search-globs org-roam-file-extensions)
" ")
(format " '\\[([^[]]++|(?R))*\\]%s' "
(mapconcat (lambda (title)
(format "|(\\b%s\\b)" (shell-quote-argument title)))
titles ""))
org-roam-directory))
(results (split-string (shell-command-to-string rg-command) "\n"))
f row col match)
(magit-insert-section (unlinked-references)
(magit-insert-heading "Unlinked References:")
(dolist (line results)
(save-match-data
(when (string-match org-roam-unlinked-references-result-re line)
(setq f (match-string 1 line)
row (string-to-number (match-string 2 line))
col (string-to-number (match-string 3 line))
match (match-string 4 line))
(when (and match
(not (f-equal-p (org-roam-node-file node) f))
(member (downcase match) (mapcar #'downcase titles)))
(magit-insert-section section (org-roam-grep-section)
(oset section file f)
(oset section row row)
(oset section col col)
(insert (propertize (format "%s:%s:%s"
(truncate-string-to-width (file-name-base f) 15 nil nil "...")
row col) 'font-lock-face 'org-roam-dim)
" "
(org-roam-fontify-like-in-org-mode
(org-roam-unlinked-references-preview-line f row))
"\n"))))))
(insert ?\n)))))
(provide 'org-roam-mode)
;;; org-roam-mode.el ends here

1049
org-roam-node.el Normal file
View File

File diff suppressed because it is too large Load Diff

441
org-roam-utils.el
View File

@ -1,12 +1,12 @@
;;; org-roam-utils.el --- Roam Research replica with Org-mode -*- coding: utf-8; lexical-binding: t -*-
;;; org-roam-utils.el --- Utilities for Org-roam -*- lexical-binding: t; -*-
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/jethrokuan/org-roam
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 0.1.2
;; Package-Requires: ((emacs "26.1"))
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.4"))
;; This file is NOT part of GNU Emacs.
@ -27,143 +27,322 @@
;;; Commentary:
;;
;; This library is an attempt at injecting Roam functionality into Org-mode.
;; This is achieved primarily through building caches for forward links,
;; backward links, and file titles.
;; This library provides definitions for utilities that used throughout the
;; whole package.
;;
;;; Code:
(require 'org)
(require 'org-element)
(require 'subr-x)
(require 'cl-lib)
;;; String utilities
;; TODO Refactor this.
(defun org-roam-replace-string (old new s)
"Replace OLD with NEW in S."
(declare (pure t) (side-effect-free t))
(replace-regexp-in-string (regexp-quote old) new s t t))
(defun org-roam--file-name-extension (filename)
"Return file name extension for FILENAME.
(defun org-roam-quote-string (s)
"Quotes string S."
(->> s
(org-roam-replace-string "\\" "\\\\")
(org-roam-replace-string "\"" "\\\"")))
Like file-name-extension, but does not strip version number."
(save-match-data
(let ((file (file-name-nondirectory filename)))
(if (and (string-match "\\.[^.]*\\'" file)
(not (eq 0 (match-beginning 0))))
(substring file (+ (match-beginning 0) 1))))))
;;; List utilities
(defmacro org-roam-plist-map! (fn plist)
"Map FN over PLIST, modifying it in-place."
(declare (indent 1))
(let ((plist-var (make-symbol "plist"))
(k (make-symbol "k"))
(v (make-symbol "v")))
`(let ((,plist-var (copy-sequence ,plist)))
(while ,plist-var
(setq ,k (pop ,plist-var))
(setq ,v (pop ,plist-var))
(setq ,plist (plist-put ,plist ,k (funcall ,fn ,k ,v)))))))
(defun org-roam--org-file-p (path)
"Check if PATH is pointing to an org file."
(let ((ext (org-roam--file-name-extension path)))
(or (string= ext "org")
(and
(string= ext "gpg")
(string= (org-roam--file-name-extension (file-name-sans-extension path)) "org")))))
(defun org-roam--find-files (dir)
"Return all `org-roam' files in `DIR'."
(if (file-exists-p dir)
(let ((files (directory-files dir t "." t))
(dir-ignore-regexp (concat "\\(?:"
"\\."
"\\|\\.\\."
"\\)$"))
result)
(dolist (file files)
(cond
((file-directory-p file)
(when (not (string-match dir-ignore-regexp file))
(setq result (append (org-roam--find-files file) result))))
((and (file-readable-p file)
(org-roam--org-file-p file))
(setq result (cons (file-truename file) result)))))
result)))
(defun org-roam--parse-content (&optional file-path)
"Parse the current buffer, and return a list of items for processing."
(org-element-map (org-element-parse-buffer) 'link
(lambda (link)
(let ((type (org-element-property :type link))
(path (org-element-property :path link))
(start (org-element-property :begin link)))
(when (and (string= type "file")
(org-roam--org-file-p path))
(goto-char start)
(let* ((element (org-element-at-point))
(begin (or (org-element-property :content-begin element)
(org-element-property :begin element)))
(content (or (org-element-property :raw-value element)
(buffer-substring
begin
(or (org-element-property :content-end element)
(org-element-property :end element)))))
(content (string-trim content))
(file-path (or file-path
(file-truename (buffer-file-name (current-buffer))))))
(list :from file-path
:to (file-truename (expand-file-name path (file-name-directory file-path)))
:properties (list :content content :point begin))))))))
(cl-defun org-roam--insert-item (item &key forward backward)
"Insert ITEM into FORWARD and BACKWARD cache.
ITEM is of the form: (:from from-path :to to-path :properties (:content preview-content :point point))."
(pcase-let ((`(:from ,p-from :to ,p-to :properties ,props) item))
;; Build forward-links
(let ((links (gethash p-from forward)))
(if links
(puthash p-from
(if (member p-to links)
links
(cons p-to links)) forward)
(puthash p-from (list p-to) forward)))
;; Build backward-links
(let ((contents-hash (gethash p-to backward)))
(if contents-hash
(if-let ((contents-list (gethash p-from contents-hash)))
(let ((updated (cons props contents-list)))
(puthash p-from updated contents-hash)
(puthash p-to contents-hash backward))
;;; File utilities
(defmacro org-roam-with-file (file keep-buf-p &rest body)
"Execute BODY within FILE.
If FILE is nil, execute BODY in the current buffer.
Kills the buffer if KEEP-BUF-P is nil, and FILE is not yet visited."
(declare (indent 2) (debug t))
`(let* (new-buf
(auto-mode-alist nil)
(buf (or (and (not ,file)
(current-buffer)) ;If FILE is nil, use current buffer
(find-buffer-visiting ,file) ; If FILE is already visited, find buffer
(progn
(puthash p-from (list props) contents-hash)
(puthash p-to contents-hash backward)))
(let ((contents-hash (make-hash-table :test #'equal)))
(puthash p-from (list props) contents-hash)
(puthash p-to contents-hash backward))))))
(setq new-buf t)
(find-file-noselect ,file)))) ; Else, visit FILE and return buffer
res)
(with-current-buffer buf
(unless (equal major-mode 'org-mode)
(delay-mode-hooks
(let ((org-inhibit-startup t)
(org-agenda-files nil))
(org-mode))))
(setq res (progn ,@body))
(unless (and new-buf (not ,keep-buf-p))
(save-buffer)))
(if (and new-buf (not ,keep-buf-p))
(when (find-buffer-visiting ,file)
(kill-buffer (find-buffer-visiting ,file))))
res))
(defun org-roam--extract-title ()
"Extract the title from `BUFFER'."
(org-element-map
(org-element-parse-buffer)
'keyword
(lambda (kw)
(when (string= (org-element-property :key kw) "TITLE")
(org-element-property :value kw)))
:first-match t))
;;; Buffer utilities
(defmacro org-roam-with-temp-buffer (file &rest body)
"Execute BODY within a temp buffer.
Like `with-temp-buffer', but propagates `org-roam-directory'.
If FILE, set `default-directory' to FILE's directory and insert its contents."
(declare (indent 1) (debug t))
(let ((current-org-roam-directory (make-symbol "current-org-roam-directory")))
`(let ((,current-org-roam-directory org-roam-directory))
(with-temp-buffer
(let ((org-roam-directory ,current-org-roam-directory))
(delay-mode-hooks (org-mode))
(when ,file
(insert-file-contents ,file)
(setq-local default-directory (file-name-directory ,file)))
,@body)))))
(defun org-roam--build-cache (dir)
"Build the org-roam caches in DIR."
(let ((backward-links (make-hash-table :test #'equal))
(forward-links (make-hash-table :test #'equal))
(file-titles (make-hash-table :test #'equal)))
(let* ((org-roam-files (org-roam--find-files dir))
(file-items (mapcar (lambda (file)
;;; Formatting
(defun org-roam-format-template (template replacer)
"Format TEMPLATE with the function REPLACER.
The templates are of form ${foo} for variable foo, and
${foo=default} for variable foo with default value \"default\".
REPLACER takes an argument of the format variable and the default
value (possibly nil). Adapted from `s-format'."
(let ((saved-match-data (match-data)))
(unwind-protect
(replace-regexp-in-string
"\\${\\([^}]+\\)}"
(lambda (md)
(let ((var (match-string 1 md))
(replacer-match-data (match-data))
default-val)
(when (string-match "\\(.+\\)=\\(.+\\)" var)
(setq default-val (match-string 2 var)
var (match-string 1 var)))
(unwind-protect
(let ((v (progn
(set-match-data saved-match-data)
(funcall replacer var default-val))))
(if v (format "%s" v) (signal 'org-roam-format-resolve md)))
(set-match-data replacer-match-data))))
template
;; Need literal to make sure it works
t t)
(set-match-data saved-match-data))))
;;; Fontification
(defun org-roam-fontify-like-in-org-mode (s)
"Fontify string S like in Org mode.
Like `org-fontify-like-in-org-mode', but supports `org-ref'."
;; NOTE: pretend that the temporary buffer created by `org-fontify-like-in-org-mode' to
;; fontify a `cite:' reference has been hacked by org-ref, whatever that means;
;;
;; `org-ref-cite-link-face-fn', which is used to supply a face for `cite:' links, calls
;; `hack-dir-local-variables' rationalizing that `bibtex-completion' would throw some warnings
;; otherwise. This doesn't seem to be the case and calling this function just before
;; `org-font-lock-ensure' (alias of `font-lock-ensure') actually instead of fixing the alleged
;; warnings messes the things so badly that `font-lock-ensure' crashes with error and doesn't let
;; org-roam to proceed further. I don't know what's happening there exactly but disabling this hackery
;; fixes the crashing. Fortunately, org-ref provides the `org-ref-buffer-hacked' switch, which we use
;; here to make it believe that the buffer was hacked.
;;
;; This is a workaround for `cite:' links and does not have any effect on other ref types.
;;
;; `org-ref-buffer-hacked' is a buffer-local variable, therefore we inline
;; `org-fontify-like-in-org-mode' here
(with-temp-buffer
(insert-file-contents file)
(org-roam--parse-content file))) org-roam-files)))
(dolist (items file-items)
(dolist (item items)
(org-roam--insert-item
item
:forward forward-links
:backward backward-links)))
(dolist (file org-roam-files)
(insert s)
(let ((org-ref-buffer-hacked t))
(org-mode)
(org-font-lock-ensure)
(buffer-string))))
;;;; Shielding regions
(defface org-roam-shielded
'((t :inherit (warning)))
"Face for regions that are shielded (marked as read-only).
This face is used on the region target by org-roam-insertion
during an `org-roam-capture'."
:group 'org-roam-faces)
(defun org-roam-shield-region (beg end)
"Shield region against modifications.
BEG and END are markers for the beginning and end regions.
REGION must be a cons-cell containing the marker to the region
beginning and maximum values."
(add-text-properties beg end
'(font-lock-face org-roam-shielded
read-only t)
(marker-buffer beg)))
(defun org-roam-unshield-region (beg end)
"Unshield the shielded REGION.
BEG and END are markers for the beginning and end regions."
(let ((inhibit-read-only t))
(remove-text-properties beg end
'(font-lock-face org-roam-shielded
read-only t)
(marker-buffer beg))))
;;; Org-mode utilities
;;;; Motions
(defun org-roam-up-heading-or-point-min ()
"Fixed version of Org's `org-up-heading-or-point-min'."
(ignore-errors (org-back-to-heading t))
(let ((p (point)))
(if (< 1 (funcall outline-level))
(progn
(org-up-heading-safe)
(when (= (point) p)
(goto-char (point-min))))
(unless (bobp) (goto-char (point-min))))))
;;;; Keywords
(defun org-roam-get-keyword (name &optional file bound)
"Return keyword property NAME from an org FILE.
FILE defaults to current file.
Only scans up to BOUND bytes of the document."
(unless bound
(setq bound 1024))
(if file
(with-temp-buffer
(insert-file-contents file)
(when-let ((title (org-roam--extract-title)))
(puthash file title file-titles)))
org-roam-files))
(list
:forward forward-links
:backward backward-links
:titles file-titles)))
(insert-file-contents file nil 0 bound)
(org-roam--get-keyword name))
(org-roam--get-keyword name bound)))
(defun org-roam--get-keyword (name &optional bound)
"Return keyword property NAME in current buffer.
If BOUND, scan up to BOUND bytes of the buffer."
(save-excursion
(let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase name))))
(goto-char (point-min))
(when (re-search-forward re bound t)
(buffer-substring-no-properties (match-beginning 1) (match-end 1))))))
(defun org-roam-set-keyword (key value)
"Set keyword KEY to VALUE.
If the property is already set, it's value is replaced."
(org-with-point-at 1
(let ((case-fold-search t))
(if (re-search-forward (concat "^#\\+" key ":\\(.*\\)") (point-max) t)
(if (string-blank-p value)
(kill-whole-line)
(replace-match (concat " " value) 'fixedcase nil nil 1))
(while (and (not (eobp))
(looking-at "^[#:]"))
(if (save-excursion (end-of-line) (eobp))
(progn
(end-of-line)
(insert "\n"))
(forward-line)
(beginning-of-line)))
(insert "#+" key ": " value "\n")))))
(defun org-roam-erase-keyword (keyword)
"Erase the line where the KEYWORD is, setting line from the top of the file."
(let ((case-fold-search t))
(org-with-point-at 1
(when (re-search-forward (concat "^#\\+" keyword ":") nil t)
(beginning-of-line)
(delete-region (point) (line-end-position))
(delete-char 1)))))
;;;; Properties
(defun org-roam-add-property (val prop)
"Add VAL value to PROP property for the node at point.
Both, VAL and PROP are strings."
(let* ((p (org-entry-get (point) prop))
(lst (when p (split-string-and-unquote p)))
(lst (if (memq val lst) lst (cons val lst)))
(lst (seq-uniq lst)))
(org-set-property prop (combine-and-quote-strings lst))
val))
(defun org-roam-remove-property (prop &optional val)
"Remove VAL value from PROP property for the node at point.
Both VAL and PROP are strings.
If VAL is not specified, user is prompted to select a value."
(let* ((p (org-entry-get (point) prop))
(lst (when p (split-string-and-unquote p)))
(prop-to-remove (or val (completing-read "Remove: " lst)))
(lst (delete prop-to-remove lst)))
(if lst
(org-set-property prop (combine-and-quote-strings lst))
(org-delete-property prop))
prop-to-remove))
;;; Logs
(defvar org-roam-verbose)
(defun org-roam-message (format-string &rest args)
"Pass FORMAT-STRING and ARGS to `message' when `org-roam-verbose' is t."
(when org-roam-verbose
(apply #'message `(,(concat "(org-roam) " format-string) ,@args))))
;;; Diagnostics
;; TODO Update this to also get commit hash
;;;###autoload
(defun org-roam-version (&optional message)
"Return `org-roam' version.
Interactively, or when MESSAGE is non-nil, show in the echo area."
(interactive)
(let* ((toplib (or load-file-name buffer-file-name))
gitdir topdir version)
(unless (and toplib (equal (file-name-nondirectory toplib) "org-roam-utils.el"))
(setq toplib (locate-library "org-roam-utils.el")))
(setq toplib (and toplib (org-roam--straight-chase-links toplib)))
(when toplib
(setq topdir (file-name-directory toplib)
gitdir (expand-file-name ".git" topdir)))
(when (file-exists-p gitdir)
(setq version
(let ((default-directory topdir))
(shell-command-to-string "git describe --tags --dirty --always"))))
(unless version
(setq version (with-temp-buffer
(insert-file-contents-literally (locate-library "org-roam.el"))
(goto-char (point-min))
(save-match-data
(if (re-search-forward "\\(?:;; Version: \\([^z-a]*?$\\)\\)" nil nil)
(substring-no-properties (match-string 1))
"N/A")))))
(if (or message (called-interactively-p 'interactive))
(message "%s" version)
version)))
(defun org-roam--straight-chase-links (filename)
"Chase links in FILENAME until a name that is not a link.
This is the same as `file-chase-links', except that it also
handles fake symlinks that are created by the package manager
straight.el on Windows.
See <https://github.com/raxod502/straight.el/issues/520>."
(when (and (bound-and-true-p straight-symlink-emulation-mode)
(fboundp 'straight-chase-emulated-symlink))
(when-let ((target (straight-chase-emulated-symlink filename)))
(unless (eq target 'broken)
(setq filename target))))
(file-chase-links filename))
;;;###autoload
(defun org-roam-diagnostics ()
"Collect and print info for `org-roam' issues."
(interactive)
(with-current-buffer (switch-to-buffer-other-window (get-buffer-create "*org-roam diagnostics*"))
(erase-buffer)
(insert (propertize "Copy info below this line into issue:\n" 'face '(:weight bold)))
(insert (format "- Emacs: %s\n" (emacs-version)))
(insert (format "- Framework: %s\n"
(condition-case _
(completing-read "I'm using the following Emacs framework:"
'("Doom" "Spacemacs" "N/A" "I don't know"))
(quit "N/A"))))
(insert (format "- Org: %s\n" (org-version nil 'full)))
(insert (format "- Org-roam: %s" (org-roam-version)))))
(provide 'org-roam-utils)
;;; org-roam-utils.el ends here

885
org-roam.el
View File

@ -1,12 +1,12 @@
;;; org-roam.el --- Roam Research replica with Org-mode -*- coding: utf-8; lexical-binding: t -*-
;;; org-roam.el --- A database abstraction layer for Org-mode -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/jethrokuan/org-roam
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 0.1.2
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (async "1.9.4"))
;; Version: 2.1.0
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
;; This file is NOT part of GNU Emacs.
@ -27,680 +27,293 @@
;;; Commentary:
;;
;; This library is an attempt at injecting Roam functionality into Org-mode.
;; This is achieved primarily through building caches for forward links,
;; backward links, and file titles.
;; Org-roam is a Roam Research inspired Emacs package and is an addition to
;; Org-mode to have a way to quickly process complex SQL-like queries over a
;; large set of plain text Org-mode files. To achieve this Org-roam provides a
;; database abstraction layer, the capabilities of which include, but are not
;; limited to:
;;
;; - Link graph traversal and visualization.
;; - Instantaneous SQL-like queries on headlines
;; - What are my TODOs, scheduled for X, or due by Y?
;; - Accessing the properties of a node, such as its tags, refs, TODO state or
;; priority.
;;
;; All of these functionality is powered by this layer. Hence, at its core
;; Org-roam's primary goal is to provide a resilient dual representation of
;; what's already available in plain text, while cached in a binary database,
;; that is cheap to maintain, easy to understand, and is as up-to-date as it
;; possibly can. For users who would like to perform arbitrary programmatic
;; queries on their Org files Org-roam also exposes an API to this database
;; abstraction layer.
;;
;; -----------------------------------------------------------------------------
;;
;; In order for the package to correctly work through your interactive session
;; it's mandatory to add somewhere to your configuration the next form:
;;
;; (org-roam-db-autosync-mode)
;;
;; The form can be called both, before or after loading the package, which is up
;; to your preferences. If you call this before the package is loaded, then it
;; will automatically load the package.
;;
;; -----------------------------------------------------------------------------
;;
;; This package also comes with a set of officially supported extensions that
;; provide extra features. You can find them in the "extensions/" subdirectory.
;; These extensions are not automatically loaded with `org-roam`, but they still
;; will be lazy-loaded through their own `autoload's.
;;
;; Org-roam also has other extensions that don't come together with this package.
;; Such extensions are distributed as their own packages, while also
;; authored and maintained by different people on distinct repositories. The
;; majority of them can be found at https://github.com/org-roam and MELPA.
;;
;;; Code:
(eval-when-compile (require 'cl-lib))
(require 'dash)
(require 'org-element)
(require 'async)
(require 'subr-x)
(require 's)
(require 'f)
(require 'org-roam-utils)
(require 'dash)
;;; Customizations
(require 'rx)
(require 'seq)
(require 'cl-lib)
(require 'magit-section)
(require 'emacsql)
(require 'emacsql-sqlite)
(require 'org)
(require 'org-id)
(require 'ol)
(require 'org-element)
(require 'org-capture)
(require 'ansi-color) ; to strip ANSI color codes in `org-roam--list-files'
(eval-when-compile
(require 'subr-x))
(require 'org-roam-utils)
(require 'org-roam-compat)
;;; Options
(defgroup org-roam nil
"Roam Research replica in Org-mode."
"A database abstraction layer for Org-mode."
:group 'org
:prefix "org-roam-"
:link '(url-link :tag "Github" "https://github.com/jethrokuan/org-roam")
:link '(url-link :tag "Online Manual" "https://org-roam.readthedocs.io/"))
:link '(url-link :tag "Github" "https://github.com/org-roam/org-roam")
:link '(url-link :tag "Online Manual" "https://www.orgroam.com/manual.html"))
(defgroup org-roam-faces nil
"Faces used by Org-roam."
:group 'org-roam
:group 'faces)
(defcustom org-roam-verbose t
"Echo messages that are not errors."
:type 'boolean
:group 'org-roam)
(defcustom org-roam-directory (expand-file-name "~/org-roam/")
"Path to Org-roam files.
All Org files, at any level of nesting, is considered part of the Org-roam."
"Default path to Org-roam files.
All Org files, at any level of nesting, are considered part of the Org-roam."
:type 'directory
:group 'org-roam)
(defcustom org-roam-new-file-directory nil
"Path to where new Org-roam files are created.
If nil, default to the org-roam-directory (preferred)."
:type 'directory
:group 'org-roam)
(defcustom org-roam-buffer-position 'right
"Position of `org-roam' buffer.
Valid values are
* left,
* right."
:type '(choice (const left)
(const right))
:group 'org-roam)
(defcustom org-roam-file-name-function #'org-roam--file-name-timestamp-title
"The function used to generate filenames.
The function takes as parameter `TITLE', a string the user inputs."
(defcustom org-roam-find-file-hook nil
"Hook run when an Org-roam file is visited."
:group 'org-roam
:type '(choice (const :tag "Default" org-roam--file-name-timestamp-title)
(function :tag "Personalized function")))
:type 'hook)
(defcustom org-roam-link-title-format "%s"
"The format string used when inserting org-roam links that use their title."
:type 'string
(defcustom org-roam-file-extensions '("org")
"List of file extensions to be included by Org-Roam.
While a file extension different from \".org\" may be used, the
file still needs to be an `org-mode' file, and it is the user's
responsibility to ensure that."
:type '(repeat string)
:group 'org-roam)
(defcustom org-roam-filename-noconfirm t
"Whether to prompt for confirmation of fil name for new files.
If nil, always ask for filename."
:type 'boolean
(defcustom org-roam-file-exclude-regexp nil
"Files matching this regular expression are excluded from the Org-roam."
:type '(choice
(string :tag "Regular expression matching files to ignore")
(const :tag "Include everything" nil))
:group 'org-roam)
(defcustom org-roam-autopopulate-title t "Whether to autopopulate the title."
:type 'boolean
:group 'org-roam)
(defcustom org-roam-list-files-commands
(if (member system-type '(windows-nt ms-dos cygwin))
nil
'(find fd fdfind rg))
"Commands that will be used to find Org-roam files.
(defcustom org-roam-buffer-width 0.33 "Width of `org-roam' buffer."
:type 'number
:group 'org-roam)
It should be a list of symbols or cons cells representing any of the following
supported file search methods.
(defcustom org-roam-buffer "*org-roam*"
"Org-roam buffer name."
:type 'string
:group 'org-roam)
The commands will be tried in order until an executable for a command is found.
The Elisp implementation is used if no command in the list is found.
(defcustom org-roam-encrypt-files nil
"Whether to encrypt new files. If true, create files with .org.gpg extension."
:type 'boolean
:group 'org-roam)
`find'
Use find as the file search method.
Example command:
find /path/to/dir -type f \( -name \"*.org\" -o -name \"*.org.gpg\" \)
(defcustom org-roam-graph-viewer (executable-find "firefox")
"Path to executable for viewing SVG."
:type 'string
:group 'org-roam)
`fd'
Use fd as the file search method.
Example command: fd /path/to/dir/ --type file -e \".org\" -e \".org.gpg\"
(defcustom org-roam-graphviz-executable (executable-find "dot")
"Path to graphviz executable."
:type 'string
:group 'org-roam)
`fdfind'
Same as `fd'. It's an alias that used in some OSes (e.g. Debian, Ubuntu)
(defcustom org-roam-graph-max-title-length 100
"Maximum length of titles in graphviz graph nodes"
:type 'number
:group 'org-roam)
`rg'
Use ripgrep as the file search method.
Example command: rg /path/to/dir/ --files -g \"*.org\" -g \"*.org.gpg\"
(defcustom org-roam-graph-node-shape "ellipse"
"Maximum length of titles in graphviz graph nodes"
:type 'string
:group 'org-roam)
By default, `executable-find' will be used to look up the path to the
executable. If a custom path is required, it can be specified together with the
method symbol as a cons cell. For example: '(find (rg . \"/path/to/rg\"))."
:type '(set (const :tag "find" find)
(const :tag "fd" fd)
(const :tag "fdfind" fdfind)
(const :tag "rg" rg)
(const :tag "elisp" nil)))
;;; Polyfills
;; These are for functions I use that are only available in newer Emacs
;;; Library
(defun org-roam-file-p (&optional file)
"Return t if FILE is an Org-roam file, nil otherwise.
If FILE is not specified, use the current buffer's file-path.
;; Introduced in Emacs 27.1
(unless (fboundp 'make-empty-file)
(defun make-empty-file (filename &optional parents)
"Create an empty file FILENAME.
Optional arg PARENTS, if non-nil then creates parent dirs as needed.
FILE is an Org-roam file if:
- It's located somewhere under `org-roam-directory'
- It has a matching file extension (`org-roam-file-extensions')
- It doesn't match excluded regexp (`org-roam-file-exclude-regexp')"
(let* ((path (or file (buffer-file-name (buffer-base-buffer))))
(ext (when path (org-roam--file-name-extension path)))
(ext (if (string= ext "gpg")
(org-roam--file-name-extension (file-name-sans-extension path))
ext)))
(save-match-data
(and
path
(member ext org-roam-file-extensions)
(not (and org-roam-file-exclude-regexp
(string-match-p org-roam-file-exclude-regexp path)))
(f-descendant-of-p path (expand-file-name org-roam-directory))))))
If called interactively, then PARENTS is non-nil."
(interactive
(let ((filename (read-file-name "Create empty file: ")))
(list filename t)))
(when (and (file-exists-p filename) (null parents))
(signal 'file-already-exists `("File exists" ,filename)))
(let ((paren-dir (file-name-directory filename)))
(when (and paren-dir (not (file-exists-p paren-dir)))
(make-directory paren-dir parents)))
(write-region "" nil filename nil 0)))
(defun org-roam-list-files ()
"Return a list of all Org-roam files under `org-roam-directory'.
See `org-roam-file-p' for how each file is determined to be as
part of Org-Roam."
(org-roam--list-files (expand-file-name org-roam-directory)))
;;; Dynamic variables
(defvar org-roam-cache-initialized nil
"Boolean value indicating whether the cache is initialized.")
(defun org-roam-buffer-p (&optional buffer)
"Return t if BUFFER is for an Org-roam file.
If BUFFER is not specified, use the current buffer."
(let ((buffer (or buffer (current-buffer)))
path)
(with-current-buffer buffer
(and (derived-mode-p 'org-mode)
(setq path (buffer-file-name (buffer-base-buffer)))
(org-roam-file-p path)))))
(defvar org-roam-forward-links-cache (make-hash-table :test #'equal)
"Cache containing forward links.")
(defvar org-roam-backward-links-cache (make-hash-table :test #'equal)
"Cache containing backward-links.")
(defvar org-roam-titles-cache (make-hash-table :test #'equal)
"Cache containing titles for org-roam files.")
(defvar org-roam--current-buffer nil
"Currently displayed file in `org-roam' buffer.")
(defvar org-roam-last-window nil
"Last window `org-roam' was called from.")
;;; Utilities
(defun org-roam--ensure-cache-built ()
"Ensures that org-roam cache is built."
(unless org-roam-cache-initialized
(org-roam--build-cache-async)
(user-error "Your Org-Roam cache isn't built yet! Please wait")))
(defun org-roam--org-roam-file-p (&optional file)
"Return t if FILE is part of org-roam system, defaulting to the name of the current buffer. Else, return nil."
(let ((path (or file
(buffer-file-name (current-buffer)))))
(and path
(org-roam--org-file-p path)
(f-descendant-of-p (file-truename path)
(file-truename org-roam-directory)))))
(defun org-roam--get-title-from-cache (file)
"Return title of `FILE' from the cache."
(or (gethash file org-roam-titles-cache)
(progn
(unless org-roam-cache-initialized
(user-error "The Org-Roam caches aren't built! Please run org-roam--build-cache-async"))
nil)))
(defun org-roam--find-all-files ()
"Return all org-roam files."
(org-roam--find-files (file-truename org-roam-directory)))
(defun org-roam--make-new-file-path (id &optional absolute)
"Make new file path from identifier `ID'.
If `ABSOLUTE', return an absolute file-path. Else, return a relative file-path."
(let ((absolute-file-path (file-truename
(expand-file-name
(if org-roam-encrypt-files
(concat id ".org.gpg")
(concat id ".org"))
(or org-roam-new-file-directory
org-roam-directory)))))
(if absolute
absolute-file-path
(file-relative-name absolute-file-path
(file-truename org-roam-directory)))))
(defun org-roam--get-title-or-slug (file-path)
"Convert `FILE-PATH' to the file title, if it exists. Else, return the path."
(or (org-roam--get-title-from-cache file-path)
(-> file-path
(file-relative-name (file-truename org-roam-directory))
(file-name-sans-extension))))
(defun org-roam--title-to-slug (title)
"Convert TITLE to a filename-suitable slug."
(let* ((s (s-downcase title))
(s (replace-regexp-in-string "[^a-zA-Z0-9_ ]" "" s))
(s (s-split " " s))
(s (s-join "_" s)))
s))
(defun org-roam--file-name-timestamp-title (title)
"Return a file name (without extension) for new files.
It uses TITLE and the current timestamp to form a unique title."
(let ((timestamp (format-time-string "%Y%m%d%H%M%S" (current-time)))
(slug (org-roam--title-to-slug title)))
(format "%s_%s" timestamp slug)))
;;; Creating org-roam files
(defun org-roam--populate-title (file &optional title)
"Populate title line for FILE using TITLE, if provided.
If not provided, derive the title from the file name."
(let ((title (or title
(-> file
(file-name-nondirectory)
(file-name-sans-extension)
(split-string "_")
(string-join " ")
(s-titleize)))))
(write-region
(concat
"#+TITLE: "
title
"\n\n")
nil file nil)))
(defun org-roam--make-file (file-path &optional title)
"Create an org-roam file at FILE-PATH, optionally setting the TITLE attribute."
(if (file-exists-p file-path)
(error (format "Aborting, file already exists at %s" file-path))
(make-empty-file file-path t)
(if org-roam-autopopulate-title
(org-roam--populate-title file-path title))
(save-excursion
(with-current-buffer (find-file-noselect file-path)
(org-roam--update-cache)))))
(defun org-roam--new-file-named (slug)
"Create a new file named `SLUG'.
`SLUG' is the short file name, without a path or a file extension."
(interactive "sNew filename (without extension): ")
(let ((file-path (org-roam--make-new-file-path slug t)))
(unless (file-exists-p file-path)
(org-roam--make-file file-path))
(find-file file-path)))
(defun org-roam--get-new-id (title)
"Return a new ID, given the note TITLE."
(let* ((proposed-slug (funcall org-roam-file-name-function title))
(new-slug (if org-roam-filename-noconfirm
proposed-slug
(read-string "Enter ID (without extension): "
proposed-slug)))
(file-path (org-roam--make-new-file-path new-slug t)))
(if (file-exists-p file-path)
(user-error "There's already a file at %s")
new-slug)))
(defun org-roam-new-file ()
"Quickly create a new file, using the current timestamp."
(interactive)
(org-roam--new-file-named (format-time-string "%Y%m%d%H%M%S" (current-time))))
;;; Inserting org-roam links
(defun org-roam-insert (prefix)
"Find an org-roam file, and insert a relative org link to it at point.
If PREFIX, downcase the title before insertion."
(interactive "P")
(let* ((completions (mapcar (lambda (file)
(list (org-roam--get-title-or-slug file)
file))
(org-roam--find-all-files)))
(title (completing-read "File: " completions))
(absolute-file-path (or (cadr (assoc title completions))
(org-roam--make-new-file-path (org-roam--get-new-id title) t)))
(current-file-path (-> (or (buffer-base-buffer)
(current-buffer))
(buffer-file-name)
(file-truename)
(file-name-directory))))
(unless (file-exists-p absolute-file-path)
(org-roam--make-file absolute-file-path title))
(insert (format "[[%s][%s]]"
(concat "file:" (file-relative-name absolute-file-path
current-file-path))
(format org-roam-link-title-format (if prefix
(downcase title)
title))))))
;;; Finding org-roam files
(defun org-roam-find-file ()
"Find and open an org-roam file."
(interactive)
(let* ((completions (mapcar (lambda (file)
(list (org-roam--get-title-or-slug file) file))
(org-roam--find-all-files)))
(title-or-slug (completing-read "File: " completions))
(absolute-file-path (or (cadr (assoc title-or-slug completions))
(org-roam--make-new-file-path
(org-roam--get-new-id title-or-slug) t))))
(unless (file-exists-p absolute-file-path)
(org-roam--make-file absolute-file-path title-or-slug))
(find-file absolute-file-path)))
(defun org-roam--get-roam-buffers ()
"Return a list of buffers that are org-roam files."
(--filter (and (with-current-buffer it (derived-mode-p 'org-mode))
(buffer-file-name it)
(org-roam--org-roam-file-p (buffer-file-name it)))
(defun org-roam-buffer-list ()
"Return a list of buffers that are Org-roam files."
(--filter (org-roam-buffer-p it)
(buffer-list)))
(defun org-roam-switch-to-buffer ()
"Switch to an existing org-roam buffer using completing-read."
(interactive)
(let* ((roam-buffers (org-roam--get-roam-buffers))
(names-and-buffers (mapcar (lambda (buffer)
(cons (or (org-roam--get-title-from-cache
(buffer-file-name buffer))
(buffer-name buffer))
buffer))
roam-buffers)))
(unless roam-buffers
(error "No roam buffers."))
(when-let ((name (completing-read "Choose a buffer: " names-and-buffers)))
(switch-to-buffer (cdr (assoc name names-and-buffers))))))
(defun org-roam--file-name-extension (filename)
"Return file name extension for FILENAME.
Like `file-name-extension', but does not strip version number."
(save-match-data
(let ((file (file-name-nondirectory filename)))
(if (and (string-match "\\.[^.]*\\'" file)
(not (eq 0 (match-beginning 0))))
(substring file (+ (match-beginning 0) 1))))))
;;; Building the org-roam cache
(defun org-roam--build-cache-async ()
"Builds the caches asychronously."
(interactive)
(async-start
`(lambda ()
(setq load-path ',load-path)
(package-initialize)
(require 'org-roam-utils)
,(async-inject-variables "org-roam-directory")
(org-roam--build-cache org-roam-directory))
(lambda (cache)
(setq org-roam-forward-links-cache (plist-get cache :forward))
(setq org-roam-backward-links-cache (plist-get cache :backward))
(setq org-roam-titles-cache (plist-get cache :titles))
(setq org-roam-cache-initialized t)
(message "Org-roam cache built!"))))
(defun org-roam--list-files (dir)
"Return all Org-roam files located recursively within DIR.
Use external shell commands if defined in `org-roam-list-files-commands'."
(let (path exe)
(cl-dolist (cmd org-roam-list-files-commands)
(pcase cmd
(`(,e . ,path)
(setq path (executable-find path)
exe (symbol-name e)))
((pred symbolp)
(setq path (executable-find (symbol-name cmd))
exe (symbol-name cmd)))
(wrong-type
(signal 'wrong-type-argument
`((consp symbolp)
,wrong-type))))
(when path (cl-return)))
(if-let* ((files (when path
(let ((fn (intern (concat "org-roam--list-files-" exe))))
(unless (fboundp fn) (user-error "%s is not an implemented search method" fn))
(funcall fn path (format "\"%s\"" dir)))))
(files (seq-filter #'org-roam-file-p files))
(files (mapcar #'expand-file-name files))) ; canonicalize names
files
(org-roam--list-files-elisp dir))))
(defun org-roam--clear-cache ()
"Clears all entries in the caches."
(interactive)
(setq org-roam-cache-initialized nil)
(setq org-roam-forward-links-cache (make-hash-table :test #'equal))
(setq org-roam-backward-links-cache (make-hash-table :test #'equal))
(setq org-roam-titles-cache (make-hash-table :test #'equal)))
(defun org-roam--shell-command-files (cmd)
"Run CMD in the shell and return a list of files.
If no files are found, an empty list is returned."
(--> cmd
(shell-command-to-string it)
(ansi-color-filter-apply it)
(split-string it "\n")
(seq-filter #'s-present? it)))
(defun org-roam--clear-file-from-cache (&optional filepath)
"Remove any related links to the file.
(defun org-roam--list-files-search-globs (exts)
"Given EXTS, return a list of search globs.
E.g. (\".org\") => (\"*.org\" \"*.org.gpg\")"
(cl-loop for e in exts
append (list (format "\"*.%s\"" e)
(format "\"*.%s.gpg\"" e))))
This is equivalent to removing the node from the graph."
(let* ((path (or filepath
(buffer-file-name (current-buffer))))
(file (file-truename path)))
;; Step 1: Remove all existing links for file
(when-let ((forward-links (gethash file org-roam-forward-links-cache)))
;; Delete backlinks to file
(dolist (link forward-links)
(when-let ((backward-links (gethash link org-roam-backward-links-cache)))
(remhash file backward-links)
(puthash link backward-links org-roam-backward-links-cache)))
;; Clean out forward links
(remhash file org-roam-forward-links-cache))
;; Step 2: Remove from the title cache
(remhash file org-roam-titles-cache)))
(defun org-roam--list-files-find (executable dir)
"Return all Org-roam files under DIR, using \"find\", provided as EXECUTABLE."
(let* ((globs (org-roam--list-files-search-globs org-roam-file-extensions))
(names (s-join " -o " (mapcar (lambda (glob) (concat "-name " glob)) globs)))
(command (s-join " " `(,executable "-L" ,dir "-type f \\(" ,names "\\)"))))
(org-roam--shell-command-files command)))
(defun org-roam--update-cache-title ()
"Insert the title of the current buffer into the cache."
(when-let ((title (org-roam--extract-title)))
(puthash (file-truename (buffer-file-name (current-buffer)))
title
org-roam-titles-cache)))
(defun org-roam--list-files-fd (executable dir)
"Return all Org-roam files under DIR, using \"fd\", provided as EXECUTABLE."
(let* ((globs (org-roam--list-files-search-globs org-roam-file-extensions))
(extensions (s-join " -e " (mapcar (lambda (glob) (substring glob 2 -1)) globs)))
(command (s-join " " `(,executable "-L" ,dir "--type file" ,extensions))))
(org-roam--shell-command-files command)))
(defun org-roam--update-cache ()
"Update org-roam caches for the current buffer file."
(save-excursion
(org-roam--clear-file-from-cache)
;; Insert into title cache
(org-roam--update-cache-title)
;; Insert new items
(let ((items (org-roam--parse-content)))
(dolist (item items)
(org-roam--insert-item
item
:forward org-roam-forward-links-cache
:backward org-roam-backward-links-cache)))
;; Rerender buffer
(org-roam--maybe-update-buffer :redisplay t)))
(defalias 'org-roam--list-files-fdfind #'org-roam--list-files-fd)
;;; Org-roam daily notes
(defun org-roam-today ()
"Create the file for today."
(interactive)
(org-roam--new-file-named (format-time-string "%Y-%m-%d" (current-time))))
(defun org-roam--list-files-rg (executable dir)
"Return all Org-roam files under DIR, using \"rg\", provided as EXECUTABLE."
(let* ((globs (org-roam--list-files-search-globs org-roam-file-extensions))
(command (s-join " " `(,executable "-L" ,dir "--files"
,@(mapcar (lambda (glob) (concat "-g " glob)) globs)))))
(org-roam--shell-command-files command)))
(defun org-roam-tomorrow ()
"Create the file for tomorrow."
(interactive)
(org-roam--new-file-named (format-time-string "%Y-%m-%d" (time-add 86400 (current-time)))))
(defun org-roam-date ()
"Create the file for any date using the calendar."
(interactive)
(let ((time (org-read-date nil 'to-time nil "Date: ")))
(org-roam--new-file-named (format-time-string "%Y-%m-%d" time))))
;;; Org-roam buffer
(define-derived-mode org-roam-backlinks-mode org-mode "Backlinks"
"Major mode for the org-roam backlinks buffer
Bindings:
\\{org-roam-backlinks-mode-map}")
(define-key org-roam-backlinks-mode-map [mouse-1] 'org-roam-jump-to-backlink)
(define-key org-roam-backlinks-mode-map (kbd "RET") 'org-roam-jump-to-backlink)
(defun org-roam-jump-to-backlink ()
"Jumps to original file and location of the backlink content snippet at point"
(interactive)
(let ((file-from (get-text-property (point) 'file-from))
(p (get-text-property (point) 'file-from-point)))
(when (and file-from p)
(find-file file-from)
(goto-char p)
(org-show-context))))
(defun org-roam--find-file (file)
"Open FILE in the window `org-roam' was called from."
(if (and org-roam-last-window (window-valid-p org-roam-last-window))
(progn (with-selected-window org-roam-last-window
(find-file file))
(select-window org-roam-last-window))
(find-file file)))
(defun org-roam-update (file-path)
"Show the backlinks for given org file for file at `FILE-PATH'."
(org-roam--ensure-cache-built)
(let ((buffer-title (org-roam--get-title-or-slug file-path)))
(with-current-buffer org-roam-buffer
;; Locally overwrite the file opening function to re-use the
;; last window org-roam was called from
(setq-local
org-link-frame-setup
(cons '(file . org-roam--find-file) org-link-frame-setup))
(let ((inhibit-read-only t))
(erase-buffer)
(when (not (eq major-mode 'org-roam-backlinks-mode))
(org-roam-backlinks-mode))
(make-local-variable 'org-return-follows-link)
(setq org-return-follows-link t)
(insert
(propertize buffer-title 'font-lock-face 'org-document-title))
(if-let ((backlinks (gethash file-path org-roam-backward-links-cache)))
(progn
(insert (format "\n\n* %d Backlinks\n"
(hash-table-count backlinks)))
(maphash (lambda (file-from contents)
(insert (format "** [[file:%s][%s]]\n"
file-from
(org-roam--get-title-or-slug file-from)))
(dolist (properties contents)
(let ((content (propertize
(s-trim (s-replace "\n" " "
(plist-get properties :content)))
'font-lock-face 'org-block
'help-echo "mouse-1: visit backlinked note"
'file-from file-from
'file-from-point (plist-get properties :point))))
(insert (format "%s \n\n" content)))))
backlinks))
(insert "\n\n* No backlinks!")))
(read-only-mode 1))))
;;; Building the Graphviz graph
(defun org-roam-build-graph ()
"Build graphviz graph output."
(org-roam--ensure-cache-built)
(with-temp-buffer
(insert "digraph {\n")
(dolist (file (org-roam--find-all-files))
(let ((title (org-roam--get-title-or-slug file)))
(let ((shortened-title (s-truncate org-roam-graph-max-title-length title)))
(insert
(format " \"%s\" [label=\"%s\", shape=%s, URL=\"roam://%s\", tooltip=\"%s\"];\n"
title
shortened-title
org-roam-graph-node-shape
file
title
)))))
(maphash
(lambda (from-link to-links)
(dolist (to-link to-links)
(insert (format " \"%s\" -> \"%s\";\n"
(org-roam--get-title-or-slug from-link)
(org-roam--get-title-or-slug to-link)))))
org-roam-forward-links-cache)
(insert "}")
(buffer-string)))
(defun org-roam-show-graph ()
"Generate the org-roam graph in SVG format, and display it using `org-roam-graph-viewer'."
(interactive)
(unless org-roam-graphviz-executable
(setq org-roam-graphviz-executable (executable-find "dot")))
(unless org-roam-graphviz-executable
(user-error "Can't find graphviz executable. Please check if it is in your path"))
(declare (indent 0))
(let ((temp-dot (expand-file-name "graph.dot" temporary-file-directory))
(temp-graph (expand-file-name "graph.svg" temporary-file-directory))
(graph (org-roam-build-graph)))
(with-temp-file temp-dot
(insert graph))
(call-process org-roam-graphviz-executable nil 0 nil temp-dot "-Tsvg" "-o" temp-graph)
(if (and org-roam-graph-viewer (executable-find org-roam-graph-viewer))
(call-process org-roam-graph-viewer nil 0 nil temp-graph)
(view-file temp-graph))))
;;; Org-roam minor mode
(cl-defun org-roam--maybe-update-buffer (&key redisplay)
"Update `org-roam-buffer' with the necessary information.
This needs to be quick/infrequent, because this is run at
`post-command-hook'."
(let ((buffer (window-buffer)))
(when (and (or redisplay
(not (eq org-roam--current-buffer buffer)))
(eq 'visible (org-roam--current-visibility))
(buffer-local-value 'buffer-file-truename buffer))
(setq org-roam--current-buffer buffer)
(org-roam-update (expand-file-name
(buffer-local-value 'buffer-file-truename buffer))))))
(defun org-roam--find-file-hook-function ()
"Called by `find-file-hook' when `org-roam-mode' is on."
(when (org-roam--org-roam-file-p)
(add-hook 'post-command-hook #'org-roam--maybe-update-buffer nil t)
(add-hook 'after-save-hook #'org-roam--update-cache nil t)))
(defvar org-roam-mode-map
(make-sparse-keymap)
"Keymap for org-roam commands.")
(defun org-roam--delete-file-advice (file &optional _trash)
"Advice for maintaining cache consistency during file deletes."
(org-roam--clear-file-from-cache (file-truename file)))
(defun org-roam--rename-file-advice (file new-file &rest args)
"Rename backlinks of FILE to refer to NEW-FILE."
(when (and (not (auto-save-file-name-p file))
(not (auto-save-file-name-p new-file))
(org-roam--org-roam-file-p new-file))
(org-roam--ensure-cache-built)
(org-roam--clear-file-from-cache file)
(let* ((files (gethash file org-roam-backward-links-cache nil))
(path (file-truename file))
(new-path (file-truename new-file))
(slug (org-roam--get-title-or-slug file))
(old-title (format org-roam-link-title-format slug))
(new-slug (or (org-roam--get-title-from-cache path)
(org-roam--get-title-or-slug new-path)))
(new-title (format org-roam-link-title-format new-slug)))
(when files
(maphash (lambda (file-from props)
(let* ((file-dir (file-name-directory file-from))
(relative-path (file-relative-name new-path file-dir))
(old-relative-path (file-relative-name path file-dir))
(slug-regex (regexp-quote (format "[[file:%s][%s]]" old-relative-path old-title)))
(named-regex (concat
(regexp-quote (format "[[file:%s][" old-relative-path))
"\\(.*\\)"
(regexp-quote "]]"))))
(with-temp-file file-from
(insert-file-contents file-from)
(while (re-search-forward slug-regex nil t)
(replace-match (format "[[file:%s][%s]]" relative-path new-title)))
(goto-char (point-min))
(while (re-search-forward named-regex nil t)
(replace-match (format "[[file:%s][\\1]]" relative-path))))
(save-window-excursion
(find-file file-from)
(org-roam--update-cache))))
files))
(save-window-excursion
(find-file new-path)
(org-roam--update-cache)))))
;;;###autoload
(define-minor-mode org-roam-mode
"Minor mode for Org-roam.
When called interactively, toggle `org-roam-mode'. with prefix ARG, enable `org-roam-mode'
if ARG is posiwive, otherwise disable it.
When called from Lisp, enable `org-roam-mode' if ARG is omitted, nil, or positive.
If ARG is `toggle', toggle `org-roam-mode'. Otherwise, behave as if called interactively."
:lighter "Org-Roam "
:keymap org-roam-mode-map
:group 'org-roam
:require 'org-roam
:global t
(cond
(org-roam-mode
(unless org-roam-cache-initialized
(org-roam--build-cache-async))
(add-hook 'find-file-hook #'org-roam--find-file-hook-function)
(advice-add 'rename-file :after #'org-roam--rename-file-advice)
(advice-add 'delete-file :before #'org-roam--delete-file-advice))
(t
(remove-hook 'find-file-hook #'org-roam--find-file-hook-function)
(advice-remove 'rename-file #'org-roam--rename-file-advice)
(advice-remove 'delete-file #'org-roam--delete-file-advice)
;; Disable local hooks for all org-roam buffers
(dolist (buf (org-roam--get-roam-buffers))
(with-current-buffer buf
(remove-hook 'post-command-hook #'org-roam--maybe-update-buffer t)
(remove-hook 'after-save-hook #'org-roam--update-cache t))))))
(defun org-roam--list-files-elisp (dir)
"Return all Org-roam files under DIR, using Elisp based implementation."
(let ((regex (concat "\\.\\(?:"(mapconcat
#'regexp-quote org-roam-file-extensions
"\\|" )"\\)\\(?:\\.gpg\\)?\\'"))
result)
(dolist (file (org-roam--directory-files-recursively dir regex nil nil t) result)
(when (and (file-readable-p file)
(org-roam-file-p file))
(push file result)))))
;;; Package bootstrap
(provide 'org-roam)
;;; Show/hide the org-roam buffer
(define-inline org-roam--current-visibility ()
"Return whether the current visibility state of the org-roam buffer.
Valid states are 'visible, 'exists and 'none."
(declare (side-effect-free t))
(inline-quote
(cond
((get-buffer-window org-roam-buffer) 'visible)
((get-buffer org-roam-buffer) 'exists)
(t 'none))))
(cl-eval-when (load eval)
(require 'org-roam-db)
(require 'org-roam-node)
(require 'org-roam-capture)
(require 'org-roam-mode)
(require 'org-roam-migrate))
(defun org-roam--set-width (width)
"Set the width of the org-roam buffer to `WIDTH'."
(unless (one-window-p)
(let ((window-size-fixed)
(w (max width window-min-width)))
(cond
((> (window-width) w)
(shrink-window-horizontally (- (window-width) w)))
((< (window-width) w)
(enlarge-window-horizontally (- w (window-width))))))))
(defun org-roam--setup-buffer ()
"Setup the `org-roam' buffer at the `org-roam-buffer-position'."
(let ((window (get-buffer-window)))
(-> (get-buffer-create org-roam-buffer)
(display-buffer-in-side-window
`((side . ,org-roam-buffer-position)))
(select-window))
(org-roam--set-width
(round (* (frame-width)
org-roam-buffer-width)))
(select-window window)))
(defun org-roam ()
"Pops up the window `org-roam-buffer' accordingly."
(interactive)
(setq org-roam-last-window (get-buffer-window))
(pcase (org-roam--current-visibility)
('visible (delete-window (get-buffer-window org-roam-buffer)))
('exists (org-roam--setup-buffer))
('none (org-roam--setup-buffer))))
;;; org-roam.el ends here
;; Local Variables:
;; outline-regexp: ";;;+ "
;; End:

6
tests/roam-files/bar.org Normal file
View File

@ -0,0 +1,6 @@
:PROPERTIES:
:ID: 440795d0-70c1-4165-993d-aebd5eef7a24
:END:
#+title: Bar
[[id:884b2341-b7fe-434d-848c-5282c0727861][Foo]]

7
tests/roam-files/f1.org
View File

@ -1,7 +0,0 @@
#+TITLE: File 1
link to [[file:nested/f1.org][Nested File 1]]
link to [[file:f2.org][File 2]]
Arbitrary [[https://google.com][HTML]] link
Arbitrary text

3
tests/roam-files/f2.org
View File

@ -1,3 +0,0 @@
#+TITLE: File 2
This file has no links.

5
tests/roam-files/f3.org
View File

@ -1,5 +0,0 @@
#+TITLE: File 3
This file has a link to an file with no title.
[[file:no-title.org][no-title]]

4
tests/roam-files/foo.org Normal file
View File

@ -0,0 +1,4 @@
:PROPERTIES:
:ID: 884b2341-b7fe-434d-848c-5282c0727861
:END:
#+title: Foo

0
tests/roam-files/markdown.md Normal file
View File

4
tests/roam-files/nested/f1.org
View File

@ -1,4 +0,0 @@
#+TITLE: Nested File 1
Link to [[file:f2.org][Nested File 2]]
Link to [[file:../f1.org][File 1]]

3
tests/roam-files/nested/f2.org
View File

@ -1,3 +0,0 @@
#+TITLE: Nested File 2
Link to [[file:f1.org][Nested File 1]]

1
tests/roam-files/no-title.org
View File

@ -1 +0,0 @@
no title in this file :O

7
tests/roam-files/roam-exclude.org Normal file
View File

@ -0,0 +1,7 @@
:PROPERTIES:
:ID: 53fadc75-f48e-461e-be06-44a1e88b2abe
:ROAM_EXCLUDE: t
:END:
#+TITLE: Excluded by Org-roam
This node is excluded by declaring ~ROAM_EXCLUDE: t~.

241
tests/test-org-roam.el
View File

@ -1,9 +1,9 @@
;;; test-org-roam.el --- Tests for org-roam -*- lexical-binding: t; -*-
;;; test-org-roam.el --- Tests for Org-roam -*- lexical-binding: t; -*-
;; Copyright (C) 2020 Jethro Kuan
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; Package-Requires: ((buttercup) (with-simulated-input))
;; Package-Requires: ((buttercup))
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
@ -19,212 +19,65 @@
;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;;
;;; Code:
;;;; Requirements
(require 'buttercup)
(require 'with-simulated-input)
(require 'org-roam)
(require 'dash)
(defun abs-path (file-path)
(file-truename (expand-file-name file-path org-roam-directory)))
(defun org-roam--test-find-new-file (path)
(let ((path (abs-path path)))
(make-directory (file-name-directory path) t)
(find-file path)))
(defvar org-roam--tests-directory (file-truename (concat default-directory "tests/roam-files"))
"Directory containing org-roam test org files.")
(defun org-roam--test-init ()
(let ((original-dir org-roam--tests-directory)
(new-dir (expand-file-name (make-temp-name "org-roam") temporary-file-directory)))
(copy-directory original-dir new-dir)
(setq org-roam-directory new-dir))
(org-roam-mode +1))
(defun org-roam--test-build-cache ()
"Builds the caches synchronously."
(let ((cache (org-roam--build-cache org-roam-directory)))
(setq org-roam-forward-links-cache (plist-get cache :forward))
(setq org-roam-backward-links-cache (plist-get cache :backward))
(setq org-roam-titles-cache (plist-get cache :titles))
(setq org-roam-cache-initialized t)))
;;; Tests
(describe "org-roam--build-cache-async"
(it "initializes correctly"
(org-roam--test-init)
(expect org-roam-cache-initialized :to-be nil)
(expect (hash-table-count org-roam-forward-links-cache) :to-be 0)
(expect (hash-table-count org-roam-backward-links-cache) :to-be 0)
(expect (hash-table-count org-roam-titles-cache) :to-be 0)
(org-roam--build-cache-async)
(sleep-for 3) ;; Because it's async
;; Caches should be populated
(expect org-roam-cache-initialized :to-be t)
(expect (hash-table-count org-roam-forward-links-cache) :to-be 4)
(expect (hash-table-count org-roam-backward-links-cache) :to-be 5)
(expect (hash-table-count org-roam-titles-cache) :to-be 5)
;; Forward cache
(let ((f1 (gethash (abs-path "f1.org") org-roam-forward-links-cache))
(f2 (gethash (abs-path "f2.org") org-roam-forward-links-cache))
(nested-f1 (gethash (abs-path "nested/f1.org") org-roam-forward-links-cache))
(nested-f2 (gethash (abs-path "nested/f2.org") org-roam-forward-links-cache))
(expected-f1 (list (abs-path "nested/f1.org")
(abs-path "f2.org")))
(expected-nested-f1 (list (abs-path "nested/f2.org")
(abs-path "f1.org")))
(expected-nested-f2 (list (abs-path "nested/f1.org"))))
(expect f1 :to-have-same-items-as expected-f1)
(expect f2 :to-be nil)
(expect nested-f1 :to-have-same-items-as expected-nested-f1)
(expect nested-f2 :to-have-same-items-as expected-nested-f2))
;; Backward cache
(let ((f1 (hash-table-keys (gethash (abs-path "f1.org") org-roam-backward-links-cache)))
(f2 (hash-table-keys (gethash (abs-path "f2.org") org-roam-backward-links-cache)))
(nested-f1 (hash-table-keys(gethash (abs-path "nested/f1.org") org-roam-backward-links-cache)))
(nested-f2 (hash-table-keys (gethash (abs-path "nested/f2.org") org-roam-backward-links-cache)))
(expected-f1 (list (abs-path "nested/f1.org")))
(expected-f2 (list (abs-path "f1.org")))
(expected-nested-f1 (list (abs-path "nested/f2.org")
(abs-path "f1.org")))
(expected-nested-f2 (list (abs-path "nested/f1.org"))))
(expect f1 :to-have-same-items-as expected-f1)
(expect f2 :to-have-same-items-as expected-f2)
(expect nested-f1 :to-have-same-items-as expected-nested-f1)
(expect nested-f2 :to-have-same-items-as expected-nested-f2))
;; Titles Cache
(expect (gethash (abs-path "f1.org") org-roam-titles-cache) :to-equal "File 1")
(expect (gethash (abs-path "f2.org") org-roam-titles-cache) :to-equal "File 2")
(expect (gethash (abs-path "nested/f1.org") org-roam-titles-cache) :to-equal "Nested File 1")
(expect (gethash (abs-path "nested/f2.org") org-roam-titles-cache) :to-equal "Nested File 2")
(expect (gethash (abs-path "no-title.org") org-roam-titles-cache) :to-be nil)))
(describe "org-roam-insert"
(describe "org-roam-list-files"
(before-each
(org-roam--test-init)
(org-roam--clear-cache)
(org-roam--test-build-cache))
(setq org-roam-directory (expand-file-name "tests/roam-files")
org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory)
org-roam-file-extensions '("org")
org-roam-file-exclude-regexp nil))
(it "temp1 -> f1"
(let ((buf (org-roam--test-find-new-file "temp1.org")))
(with-current-buffer buf
(with-simulated-input
"File SPC 1 RET"
(org-roam-insert nil))))
(expect (buffer-string) :to-match (regexp-quote "file:f1.org")))
(it "gets files correctly"
(expect (length (org-roam-list-files))
:to-equal 3))
(it "temp2 -> nested/f1"
(let ((buf (org-roam--test-find-new-file "temp2.org")))
(with-current-buffer buf
(with-simulated-input
"Nested SPC File SPC 1 RET"
(org-roam-insert nil))))
(expect (buffer-string) :to-match (regexp-quote "file:nested/f1.org")))
(it "respects org-roam-file-extensions"
(setq org-roam-file-extensions '("md"))
(expect (length (org-roam-list-files)) :to-equal 1)
(setq org-roam-file-extensions '("org" "md"))
(expect (length (org-roam-list-files)) :to-equal 4))
(it "nested/temp3 -> f1"
(let ((buf (org-roam--test-find-new-file "nested/temp3.org")))
(with-current-buffer buf
(with-simulated-input
"File SPC 1 RET"
(org-roam-insert nil))))
(expect (buffer-string) :to-match (regexp-quote "file:../f1.org")))
(it "respects org-roam-file-exclude-regexp"
(setq org-roam-file-exclude-regexp (regexp-quote "foo.org"))
(expect (length (org-roam-list-files)) :to-equal 2)))
(it "a/b/temp4 -> nested/f1"
(let ((buf (org-roam--test-find-new-file "a/b/temp4.org")))
(with-current-buffer buf
(with-simulated-input
"Nested SPC File SPC 1 RET"
(org-roam-insert nil))))
(expect (buffer-string) :to-match (regexp-quote "file:../../nested/f1.org"))))
(describe "org-roam-db-sync"
(before-all
(setq org-roam-directory (expand-file-name "tests/roam-files")
org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory)
org-roam-file-extensions '("org")
org-roam-file-exclude-regexp nil)
(org-roam-db-sync))
(describe "rename file updates cache"
(before-each
(org-roam--test-init)
(org-roam--clear-cache)
(org-roam--test-build-cache))
(after-all
(org-roam-db--close)
(delete-file org-roam-db-location))
(it "f1 -> new_f1"
(rename-file (abs-path "f1.org")
(abs-path "new_f1.org"))
;; Cache should be cleared of old file
(expect (gethash (abs-path "f1.org") org-roam-forward-links-cache) :to-be nil)
(expect (->> org-roam-backward-links-cache
(gethash (abs-path "nested/f1.org"))
(hash-table-keys)
(member (abs-path "f1.org"))) :to-be nil)
(it "has the correct number of files"
(expect (caar (org-roam-db-query [:select (funcall count) :from files]))
:to-equal
3))
(expect (->> org-roam-forward-links-cache
(gethash (abs-path "new_f1.org"))) :not :to-be nil)
(it "has the correct number of nodes"
(expect (caar (org-roam-db-query [:select (funcall count) :from nodes]))
:to-equal
2))
(expect (->> org-roam-forward-links-cache
(gethash (abs-path "new_f1.org"))
(member (abs-path "nested/f1.org"))) :not :to-be nil)
;; Links are updated
(expect (with-temp-buffer
(insert-file-contents (abs-path "nested/f1.org"))
(buffer-string)) :to-match (regexp-quote "[[file:../new_f1.org][File 1]]")))
(it "has the correct number of links"
(expect (caar (org-roam-db-query [:select (funcall count) :from links]))
:to-equal
1))
(it "respects ROAM_EXCLUDE"
;; The excluded node has ID "53fadc75-f48e-461e-be06-44a1e88b2abe"
(expect (mapcar #'car (org-roam-db-query [:select id :from nodes]))
:to-have-same-items-as
'("884b2341-b7fe-434d-848c-5282c0727861" "440795d0-70c1-4165-993d-aebd5eef7a24"))))
(it "f1 -> f1 with spaces"
(rename-file (abs-path "f1.org")
(abs-path "f1 with spaces.org"))
;; Cache should be cleared of old file
(expect (gethash (abs-path "f1.org") org-roam-forward-links-cache) :to-be nil)
(expect (->> org-roam-backward-links-cache
(gethash (abs-path "nested/f1.org"))
(hash-table-keys)
(member (abs-path "f1.org"))) :to-be nil)
;; Links are updated
(expect (with-temp-buffer
(insert-file-contents (abs-path "nested/f1.org"))
(buffer-string)) :to-match (regexp-quote "[[file:../f1 with spaces.org][File 1]]")))
(provide 'test-org-roam)
(it "no-title -> meaningful-title"
(rename-file (abs-path "no-title.org")
(abs-path "meaningful-title.org"))
;; File has no forward links
(expect (gethash (abs-path "no-title.org") org-roam-forward-links-cache) :to-be nil)
(expect (gethash (abs-path "meaningful-title.org") org-roam-forward-links-cache) :to-be nil)
(expect (->> org-roam-forward-links-cache
(gethash (abs-path "f3.org"))
(member (abs-path "no-title.org"))) :to-be nil)
(expect (->> org-roam-forward-links-cache
(gethash (abs-path "f3.org"))
(member (abs-path "meaningful-title.org"))) :not :to-be nil)
;; Links are updated with the appropriate name
(expect (with-temp-buffer
(insert-file-contents (abs-path "f3.org"))
(buffer-string)) :to-match (regexp-quote "[[file:meaningful-title.org][meaningful-title]]"))))
(describe "delete file updates cache"
(before-each
(org-roam--test-init)
(org-roam--clear-cache)
(org-roam--test-build-cache))
(it "delete f1"
(delete-file (abs-path "f1.org"))
(expect (->> org-roam-forward-links-cache
(gethash (abs-path "f1.org"))) :to-be nil)
(expect (->> org-roam-backward-links-cache
(gethash (abs-path "nested/f1.org"))
(gethash (abs-path "f1.org"))) :to-be nil)
(expect (->> org-roam-backward-links-cache
(gethash (abs-path "nested/f1.org"))
(gethash (abs-path "nested/f2.org"))) :not :to-be nil)))
;;; test-org-roam.el ends here