awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-31 14:43:32 -05:00
Code Issues Packages Projects Releases Wiki Activity

Simplify org-roam-insert and org-roam-find-file (#62)

Browse Source 
* Simplify org-roam-insert and org-roam-find-file

See #59.

* Add docs for org-roam automatic filenaming

* Update installation instructions
This commit is contained in:
Jethro Kuan
2020-02-13 00:25:45 +08:00
committed by GitHub
parent a2a448d7d2
commit 791c059200
4 changed files with 107 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
doc/configuration.md Normal file
View File

@@ -0,0 +1,51 @@
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`.
## 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 specified by the string
`org-roam-file-format`, which defaults to `"%Y%m%d%H%M%S"`. To see
valid specifications, see the help (`C-h f`) for `format-time-string`.
There are several reasons for keeping filenames meaningful. For
example, one may wish to publish the Org files, and some publishing
methods such as Org-publish use the file names as slugs for the URLs.
If you wish to maintain manual control of filenames, set
`org-roam-use-timestamp-as-filename` to `nil`:
```emacs-lisp
(setq org-roam-use-timestamp-as-filename nil)
```
When this setting is turned off, the user is instead manually prompted
for a filename. 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.

5
doc/installation.md
View File

@@ -10,7 +10,6 @@ The recommended method is using [use-package][use-package] and
:straight (:host github :repo "jethrokuan/org-roam")
:custom
(org-roam-directory "/path/to/org-files/")
(org-roam-link-representation 'title) ;; or keep it as 'id
:bind
("C-c n l" . org-roam)
("C-c n t" . org-roam-today)
@@ -31,5 +30,9 @@ git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
(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