-
-
Notifications
You must be signed in to change notification settings - Fork 59
/
denote.el
5591 lines (4749 loc) · 235 KB
/
denote.el
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;;; denote.el --- Simple notes with an efficient file-naming scheme -*- lexical-binding: t -*-
;; Copyright (C) 2022-2025 Free Software Foundation, Inc.
;; Author: Protesilaos Stavrou <[email protected]>
;; Maintainer: Protesilaos Stavrou <[email protected]>
;; URL: https://github.com/protesilaos/denote
;; Version: 3.1.0
;; Package-Requires: ((emacs "28.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 of the License, 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 this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Denote aims to be a simple-to-use, focused-in-scope, and effective
;; note-taking and file-naming tool for Emacs.
;;
;; Denote is based on the idea that files should follow a predictable
;; and descriptive file-naming scheme. The file name must offer a
;; clear indication of what the contents are about, without reference
;; to any other metadata. Denote basically streamlines the creation
;; of such files or file names while providing facilities to link
;; between them (where those files are editable).
;;
;; Denote's file-naming scheme is not limited to "notes". It can be used
;; for all types of file, including those that are not editable in Emacs,
;; such as videos. Naming files in a consistent way makes their
;; filtering and retrieval considerably easier. Denote provides relevant
;; facilities to rename files, regardless of file type.
;;
;; The manual describes all the technicalities about the file-naming
;; scheme, points of entry to creating new notes, commands to check
;; links between notes, and more: ;; <https://protesilaos.com/emacs/denote>.
;; If you have the info manual available, evaluate:
;;
;; (info "(denote) Top")
;;
;; What follows is a general overview of its core core design
;; principles (again: please read the manual for the technicalities):
;;
;; * Predictability :: File names must follow a consistent and
;; descriptive naming convention (see the manual's "The file-naming
;; scheme"). The file name alone should offer a clear indication of
;; what the contents are, without reference to any other metadatum.
;; This convention is not specific to note-taking, as it is pertinent
;; to any form of file that is part of the user's long-term storage
;; (see the manual's "Renaming files").
;;
;; * Composability :: Be a good Emacs citizen, by integrating with other
;; packages or built-in functionality instead of re-inventing
;; functions such as for filtering or greping. The author of Denote
;; (Protesilaos, aka "Prot") writes ordinary notes in plain text
;; (`.txt'), switching on demand to an Org file only when its expanded
;; set of functionality is required for the task at hand (see the
;; manual's "Points of entry").
;;
;; * Portability :: Notes are plain text and should remain portable.
;; The way Denote writes file names, the front matter it includes in
;; the note's header, and the links it establishes must all be
;; adequately usable with standard Unix tools. No need for a databse
;; or some specialised software. As Denote develops and this manual
;; is fully fleshed out, there will be concrete examples on how to do
;; the Denote-equivalent on the command-line.
;;
;; * Flexibility :: Do not assume the user's preference for a
;; note-taking methodology. Denote is conceptually similar to the
;; Zettelkasten Method, which you can learn more about in this
;; detailed introduction: <https://zettelkasten.de/introduction/>.
;; Notes are atomic (one file per note) and have a unique identifier.
;; However, Denote does not enforce a particular methodology for
;; knowledge management, such as a restricted vocabulary or mutually
;; exclusive sets of keywords. Denote also does not check if the user
;; writes thematically atomic notes. It is up to the user to apply
;; the requisite rigor and/or creativity in pursuit of their preferred
;; workflow (see the manual's "Writing metanotes").
;;
;; * Hackability :: Denote's code base consists of small and reusable
;; functions. They all have documentation strings. The idea is to
;; make it easier for users of varying levels of expertise to
;; understand what is going on and make surgical interventions where
;; necessary (e.g. to tweak some formatting). In this manual, we
;; provide concrete examples on such user-level configurations (see
;; the manual's "Keep a journal or diary").
;;
;; Now the important part... "Denote" is the familiar word, though it
;; also is a play on the "note" concept. Plus, we can come up with
;; acronyms, recursive or otherwise, of increasingly dubious utility
;; like:
;;
;; + Don't Ever Note Only The Epiphenomenal
;; + Denote Everything Neatly; Omit The Excesses
;;
;; But we'll let you get back to work. Don't Eschew or Neglect your
;; Obligations, Tasks, and Engagements.
;;; Code:
(require 'seq)
(require 'xref)
(require 'dired)
(eval-when-compile (require 'subr-x))
(defgroup denote ()
"Simple notes with an efficient file-naming scheme."
:group 'files
:link '(info-link "(denote) Top")
:link '(url-link :tag "Homepage" "https://protesilaos.com/emacs/denote"))
;;;; User options
;; About the autoload: (info "(elisp) File Local Variables")
(define-obsolete-variable-alias
'denote-user-enforced-denote-directory
'denote-directory
"2.3.0")
;;;###autoload (put 'denote-directory 'safe-local-variable (lambda (val) (or (stringp val) (eq val 'local) (eq val 'default-directory))))
(defcustom denote-directory (expand-file-name "~/Documents/notes/")
"Directory for storing personal notes.
If you intend to reference this variable in Lisp, consider using
the function `denote-directory' instead."
:group 'denote
:safe (lambda (val) (or (stringp val) (eq val 'local) (eq val 'default-directory)))
:package-version '(denote . "2.0.0")
:link '(info-link "(denote) Maintain separate directories for notes")
:type 'directory)
(define-obsolete-variable-alias 'denote-save-buffer-after-creation 'denote-save-buffers "3.0.0")
(defcustom denote-save-buffers nil
"Control whether commands that handle new notes save their buffer outright.
The default behaviour of commands such as `denote' (or related)
is to not save the buffer they create. This gives the user the
chance to review the text before writing it to a file. The user
may choose to delete the unsaved buffer, thus not creating a new
note.
This option also applies to notes affected by the renaming
commands (`denote-rename-file' and related).
If this user option is set to a non-nil value, such buffers are
saved automatically. The assumption is that the user who opts in
to this feature is familiar with the `denote-rename-file'
operation (or related) and knows it is reliable. Data loss may
occur if the file is modified externally.
Also see `denote-kill-buffers'."
:group 'denote
:package-version '(denote . "3.0.0")
:type 'boolean)
(defcustom denote-kill-buffers nil
"Control whether creation or renaming commands kill their buffer.
The default behaviour of creation or renaming commands such as
`denote' or `denote-rename-file' is to not kill the buffer they
create or modify at the end of their operation.
If this user option is nil (the default), buffers affected by a
creation or renaming command are not automatically killed.
If set to `on-creation', new notes are automatically killed.
If set to `on-rename', renamed notes are automatically killed.
If set to t, new and renamed notes are killed.
If a buffer is killed, it is also saved, as if `denote-save-buffers'
were t. See its documentation.
In all cases, if the buffer already existed before the Denote operation
it is NOT automatically killed."
:group 'denote
:package-version '(denote . "3.1.0")
:type '(choice
(const :tag "Do not kill buffers" nil)
(const :tag "Kill after creation" on-creation)
(const :tag "Kill after rename" on-rename)
(const :tag "Kill after creation and rename" t)))
;;;###autoload (put 'denote-known-keywords 'safe-local-variable #'listp)
(defcustom denote-known-keywords
'("emacs" "philosophy" "politics" "economics")
"List of strings with predefined keywords for `denote'.
Also see user options: `denote-infer-keywords',
`denote-sort-keywords', `denote-file-name-slug-functions'."
:group 'denote
:safe #'listp
:package-version '(denote . "0.1.0")
:type '(repeat string))
;;;###autoload (put 'denote-infer-keywords 'safe-local-variable (lambda (val) (or val (null val))))
(defcustom denote-infer-keywords t
"Whether to infer keywords from existing notes' file names.
When non-nil, search the file names of existing notes in the
variable `denote-directory' for their keyword field and extract
the entries as \"inferred keywords\". These are combined with
`denote-known-keywords' and are presented as completion
candidates while using `denote' and related commands
interactively.
If nil, refrain from inferring keywords. The aforementioned
completion prompt only shows the `denote-known-keywords'. Use
this if you want to enforce a restricted vocabulary.
The user option `denote-excluded-keywords-regexp' can be used to
exclude keywords that match a regular expression.
Inferred keywords are specific to the value of the variable
`denote-directory'. If a silo with a local value is used, as
explained in that variable's doc string, the inferred keywords
are specific to the given silo.
For advanced Lisp usage, the function `denote-keywords' returns
the appropriate list of strings."
:group 'denote
:safe (lambda (val) (or val (null val)))
:package-version '(denote . "0.1.0")
:type 'boolean)
(defcustom denote-prompts '(title keywords)
"Specify the prompts followed by relevant Denote commands.
Commands that prompt for user input to construct a Denote file name
include, but are not limited to: `denote', `denote-signature',
`denote-type', `denote-date', `denote-subdirectory',
`denote-rename-file', `denote-dired-rename-files'.
The value of this user option is a list of symbols, which includes any
of the following:
- `title': Prompt for the title of the new note.
- `keywords': Prompts with completion for the keywords of the new
note. Available candidates are those specified in the user
option `denote-known-keywords'. If the user option
`denote-infer-keywords' is non-nil, keywords in existing note
file names are included in the list of candidates. The
`keywords' prompt uses `completing-read-multiple', meaning that
it can accept multiple keywords separated by a comma (or
whatever the value of `crm-separator' is).
- `file-type': Prompts with completion for the file type of the
new note. Available candidates are those specified in the user
option `denote-file-type'. Without this prompt, `denote' uses
the value of the variable `denote-file-type'.
- `subdirectory': Prompts with completion for a subdirectory in
which to create the note. Available candidates are the value
of the user option `denote-directory' and all of its
subdirectories. Any subdirectory must already exist: Denote
will not create it.
- `date': Prompts for the date of the new note. It will expect
an input like 2022-06-16 or a date plus time: 2022-06-16 14:30.
Without the `date' prompt, the `denote' command uses the
`current-time'. (To leverage the more sophisticated Org
method, see the `denote-date-prompt-use-org-read-date'.)
- `template': Prompts for a KEY among `denote-templates'. The
value of that KEY is used to populate the new note with
content, which is added after the front matter.
- `signature': Prompts for an arbitrary string that can be used
to qualify the note according to the user's methodology.
Signatures have no strictly defined function and are up to the
user to apply as they see fit. One use-case is to implement
Niklas Luhmann's Zettelkasten system for a sequence of notes
(Folgezettel). Signatures are not included in a file's front
matter. They are reserved solely for creating a structure in a
file listing. To insert a link that includes the signature,
use the command `denote-link-with-signature'.
The prompts occur in the given order.
If the value of this user option is nil, no prompts are used. The
resulting file name will consist of an identifier (i.e. the date and
time) and a supported file type extension (per the variable
`denote-file-type').
Recall that Denote's standard file-naming scheme is defined as
follows (read the manual for the technicalities):
DATE--TITLE__KEYWORDS.EXT
Depending on the inclusion of the `title', `keywords', and
`signature' prompts, file names will be any of those
permutations:
DATE.EXT
DATE--TITLE.EXT
DATE__KEYWORDS.EXT
DATE==SIGNATURE.EXT
DATE==SIGNATURE--TITLE.EXT
DATE==SIGNATURE--TITLE__KEYWORDS.EXT
DATE==SIGNATURE__KEYWORDS.EXT
When in doubt, always include the `title' and `keywords'
prompts (the default style).
Finally, this user option only affects the interactive use of the
`denote' or other relevant commands (advanced users can call it from
Lisp). In Lisp usage, the behaviour is always what the caller
specifies, based on the supplied arguments.
Also see `denote-history-completion-in-prompts'.
To change the order of the file name components, refer to
`denote-file-name-components-order'."
:group 'denote
:package-version '(denote . "2.3.0")
:link '(info-link "(denote) The denote-prompts option")
:type '(radio (const :tag "Use no prompts" nil)
(set :tag "Available prompts" :greedy t
(const :tag "Title" title)
(const :tag "Keywords" keywords)
(const :tag "Date" date)
(const :tag "File type extension" file-type)
(const :tag "Subdirectory" subdirectory)
(const :tag "Template" template)
(const :tag "Signature" signature))))
(defcustom denote-file-name-components-order '(identifier signature title keywords)
"Specify the order of the file name components.
The value is a list of the following symbols:
- `identifier': This is the combination of the date and time. When it
is the first on the list, it looks like \"20240519T073456\" and does
not have a component separator of its own due its unambiguous format.
When it is placed anywhere else in the file name, it is prefixed with
\"@@\", so it looks like \"@@20240519T073456\".
- `signature': This is an arbitrary string that can be used to qualify
the file in some way, according to the user's methodology (e.g. to add
a sequence to notes). The string is always prefixed with the \"==\"
to remain unambiguous.
- `title': This is an arbitrary string which describes the file. It is
always prefixed with \"--\" to be unambiguous.
- `keywords': This is a series of one or more words that succinctly
group the file. Multiple keywords are separated by an underscore
prefixed to each of them. The file name component is always prefixed
with \"__\".
All four symbols must appear exactly once. Duplicates are ignored. Any
missing symbol is added automatically.
Some examples:
(setq denote-file-name-components-order
\\='(identifier signature title keywords))
=> 20240519T07345==hello--this-is-the-title__denote_testing.org
(setq denote-file-name-components-order
\\='(signature identifier title keywords))
=> ==hello@@20240519T07345--this-is-the-title__denote_testing.org
(setq denote-file-name-components-order
\\='(title signature identifier keywords))
=> --this-is-the-title==hello@@20240519T07345__denote_testing.org
(setq denote-file-name-components-order
\\='(keywords title signature identifier))
=> __denote_testing--this-is-the-title==hello@@20240519T07345.org
Also see the user option `denote-prompts', which affects which
components are actually used in the order specified herein.
Before deciding on this, please consider the longer-term implications
of file names with varying patterns. Consistency makes things
predictable and thus easier to find. So pick one order and never touch
it again. When in doubt, leave the default file-naming scheme as-is."
:group 'denote
:package-version '(denote . "3.0.0")
;; FIXME 2024-05-19: This technically works to display the user
;; option in the Custom buffer and to show its current value, though
;; it does not allow the user to modify it graphically: they have to
;; switch to the Lisp expression. Find a way to present an
;; interface that lets the user reorder those elements.
;;
;; Still, making this a defcustom helps with discoverability, as
;; well as with the use of `setopt' and related.
:type '(list
(const :tag "Identifier component (date and time)" identifier)
(const :tag "File signature (text to qualify a file)" signature)
(const :tag "The title of the file" title)
(const :tag "Keywords of the file" keywords)))
(defcustom denote-front-matter-components-present-even-if-empty-value '(title keywords date identifier)
"The components that are always present in front matter even when empty.
Components are `title', `keywords', `signature', `date', `identifier'.
Note that even though a component may be listed in this variable, it
will not be present in the front matter if the corresponding line is not
in the front matter template."
:group 'denote
:package-version '(denote . "3.2.0")
:type '(list
(const :tag "Title" title)
(const :tag "Keywords" keywords)
(const :tag "Signature" signature)
(const :tag "Date" date)
(const :tag "Identifier" identifier)))
(defcustom denote-sort-keywords t
"Whether to sort keywords in new files.
When non-nil, the keywords of `denote' are sorted with
`string-collate-lessp' regardless of the order they were inserted at the
minibuffer prompt.
If nil, show the keywords in their given order."
:group 'denote
:package-version '(denote . "0.1.0")
:type 'boolean)
(defcustom denote-file-type nil
"The file type extension for new notes.
By default (a nil value), the file type is that of Org mode.
Though the `org' symbol can be specified for the same effect.
When the value is the symbol `markdown-yaml', the file type is
that of Markdown mode and the front matter uses YAML notation.
Similarly, `markdown-toml' is Markdown but has TOML syntax in the
front matter.
When the value is `text', the file type is that of Text mode.
Any other non-nil value is the same as the default.
NOTE: Expert users can change the supported file-types by editing
the value of `denote-file-types'. That variable, which is not a
user option, controls the behaviour of all file-type-aware
functions (creating notes, renaming them, inserting front matter,
formatting a link, etc.). Consult its documentation for the
technicalities."
:type '(choice
(const :tag "Unspecified (defaults to Org)" nil)
(const :tag "Org mode (default)" org)
(const :tag "Markdown (YAML front matter)" markdown-yaml)
(const :tag "Markdown (TOML front matter)" markdown-toml)
(const :tag "Plain text" text))
:package-version '(denote . "0.6.0")
:group 'denote)
(defcustom denote-date-format nil
"Date format in the front matter (file header) of new notes.
When nil (the default value), use a file-type-specific
format (also check the user option `denote-file-type'):
- For Org, an inactive timestamp is used, such as [2022-06-30 Wed
15:31].
- For Markdown, the RFC3339 standard is applied:
2022-06-30T15:48:00+03:00.
- For plain text, the format is that of ISO 8601: 2022-06-30.
If the value is a string, ignore the above and use it instead.
The string must include format specifiers for the date. These
are described in the doc string of `format-time-string'."
:type '(choice
(const :tag "Use appropiate format for each file type" nil)
(string :tag "Custom format for `format-time-string'"))
:package-version '(denote . "0.2.0")
:group 'denote)
(defcustom denote-date-prompt-use-org-read-date nil
"Whether to use `org-read-date' in date prompts.
If non-nil, use `org-read-date'. If nil, input the date as a
string, as described in `denote'.
This option is relevant when `denote-prompts' includes a `date'
and/or when the user invokes the command `denote-date'."
:group 'denote
:package-version '(denote . "0.6.0")
:type 'boolean)
(defcustom denote-org-store-link-to-heading 'id
"Determine whether `org-store-link' links to the current Org heading.
[ Remember that what `org-store-link' does is merely collect a link. To
actually insert it, use the command `org-insert-link'. Note that
`org-capture' uses `org-store-link' internally when it needs to store
a link. ]
When the value is nil, the Denote handler for `org-store-link' produces
links only to the current file (by using the file's identifier). For
example:
[[denote:20240118T060608][Some test]]
This is what Denote was doing in versions prior to 2.3.0.
If the value is `context', the link consists of the file's identifier
and the text of the current heading, like this:
[[denote:20240118T060608::*Heading text][Some test::Heading text]].
However, if there already exists a CUSTOM_ID property for the current
heading, this is always given priority and is used instead of the
context.
If the value is `id' or, for backward-compatibility, any other non-nil
value, then Denote will use the standard Org mechanism of the CUSTOM_ID
property to create a unique link to the heading. If the heading does
not have a CUSTOM_ID, it creates it and includes it in its PROPERTIES
drawer. If a CUSTOM_ID exists, it takes it as-is. The result is like
this:
[[denote:20240118T060608::#h:eed0fb8e-4cc7-478f][Some test::Heading text]]
The value of the CUSTOM_ID is determined by the Org user option
`org-id-method'. The sample shown above uses the default UUID
infrastructure (though I deleted a few characters to not get
complaints from the byte compiler about long lines in the doc
string...).
Note that this option does not affect how Org behaves with regard to
`org-id-link-to-org-use-id'. If that user option is set to create ID
properties, then those will be created by Org even if the Denote link
handler will take care to not use/store the ID value. Concretely, users
who never want ID properties under their headings should keep
`org-id-link-to-org-use-id' in its nil value.
Context links are easier to break than those with a CUSTOM_ID in cases
where either the heading text changes or there is another heading that
matches that text. The potential advantage of context links is that
they do not require a PROPERTIES drawer.
When visiting a link to a heading, Org opens the Denote file and then
navigates to that heading.
[ This feature only works in Org mode files, as other file types
do not have a linking mechanism that handles unique identifiers
for headings or other patterns to jump to. If `org-store-link'
is invoked in one such file, it captures only the Denote
identifier of the file, even if this user option is set to a
non-nil value. ]"
:group 'denote
:package-version '(denote . "3.2.0")
:type '(choice (const :tag "No link to heading" nil)
(const :tag "Link to the context" context)
(const :tag "Link wtih CUSTOM_ID" id)))
(defcustom denote-templates nil
"Alist of content templates for new notes.
A template is arbitrary text that Denote will add to a newly
created note right below the front matter.
Templates are expressed as a (KEY . VALUE) association.
- The KEY is the name which identifies the template. It is an
arbitrary symbol, such as `report', `memo', `statement'.
- The VALUE is either a string or the symbol of a function.
- If it is a string, it is ordinary text that Denote will insert
as-is. It can contain newline characters to add spacing. The
manual of Denote contains examples on how to use the `concat'
function, beside writing a generic string.
- If it is a function, it is called without arguments and is expected
to return a string. Denote will call the function and insert the
result in the buffer.
The user can choose a template either by invoking the command
`denote-template' or by changing the user option `denote-prompts'
to always prompt for a template when calling the `denote'
command."
:type '(alist :key-type symbol :value-type (choice string function))
:package-version '(denote . "3.1.0")
:link '(info-link "(denote) The denote-templates option")
:group 'denote)
(defcustom denote-backlinks-show-context nil
"When non-nil, show link context in the backlinks buffer.
The context is the line a link to the current note is found in.
The context includes multiple links to the same note, if those
are present.
When nil, only show a simple list of file names that link to the
current note."
:group 'denote
:package-version '(denote . "1.2.0")
:type 'boolean)
(make-obsolete-variable 'denote-rename-no-confirm 'denote-rename-confirmations "3.0.0")
(define-obsolete-variable-alias
'denote-link-backlinks-display-buffer-action
'denote-backlinks-display-buffer-action
"3.1.0")
(defcustom denote-backlinks-display-buffer-action
'((display-buffer-reuse-window display-buffer-below-selected)
(window-height . fit-window-to-buffer)
(dedicated . t))
"The action used to display the current file's backlinks buffer.
The value has the form (FUNCTION . ALIST), where FUNCTION is
either an \"action function\", a list thereof, or possibly an
empty list. ALIST is a list of \"action alist\" which may be
omitted (or be empty).
Sample configuration to display the buffer in a side window on
the left of the Emacs frame:
(setq denote-backlinks-display-buffer-action
(quote ((display-buffer-reuse-window display-buffer-in-side-window)
(side . left)
(slot . 99)
(window-width . 0.3)
(dedicated . t)
(preserve-size . (t . t)))))
See Info node `(elisp) Displaying Buffers' for more details
and/or the documentation string of `display-buffer'."
:type '(cons (choice (function :tag "Display Function")
(repeat :tag "Display Functions" function))
alist)
:package-version '(denote . "3.1.0")
:group 'denote)
(defcustom denote-rename-confirmations '(rewrite-front-matter modify-file-name)
"Make renaming commands prompt for confirmations.
This affects the behaviour of renaming commands. The value is either
nil, in which case no confirmation is ever requested, or a list of
symbols among the following:
- `modify-file-name' means that renaming commands will ask for
confirmation before modifying the file name.
- `rewrite-front-matter' means that renaming commands will ask for
confirmation before rewritting the front matter.
- `add-front-matter' means that renaming commands will ask for
confirmation before adding new front matter to the file.
The default behaviour of the `denote-rename-file' command (and others
like it) is to ask for an affirmative answer as a final step before
changing the file name and, where relevant, inserting or updating the
corresponding front matter.
Specialized commands that build on top of `denote-rename-file' (or
related) may internally bind this user option to a non-nil value in
order to perform their operation (e.g. `denote-dired-rename-files' goes
through each marked Dired file, prompting for the information to use,
but carries out the renaming without asking for confirmation)."
:group 'denote
:type '(radio (const :tag "Disable all confirmations" nil)
(set :tag "Available confirmations" :greedy t
(const :tag "Add front matter" add-front-matter)
(const :tag "Rewrite front matter" rewrite-front-matter)
(const :tag "Modify file name" modify-file-name))))
(defcustom denote-excluded-directories-regexp nil
"Regular expression of directories to exclude from all operations.
Omit matching directories from file prompts and also exclude them
from all functions that check the contents of the variable
`denote-directory'. The regexp needs to match only the name of
the directory, not its full path.
File prompts are used by several commands, such as `denote-link'
and `denote-subdirectory'.
Functions that check for files include `denote-directory-files'
and `denote-directory-subdirectories'.
The match is performed with `string-match-p'."
:group 'denote
:package-version '(denote . "1.2.0")
:type 'string)
(defcustom denote-excluded-keywords-regexp nil
"Regular expression of keywords to not infer.
Keywords are inferred from file names and provided at relevant
prompts as completion candidates when the user option
`denote-infer-keywords' is non-nil.
The match is performed with `string-match-p'."
:group 'denote
:package-version '(denote . "1.2.0")
:type 'string)
(defcustom denote-excluded-files-regexp nil
"Regular expression of files that are excluded from Denote file prompts.
Files are provided for completion when using commands like `denote-link'
and `denote-open-or-create'.
The match is performed with `string-match-p' on the full file path."
:group 'denote
:package-version '(denote . "3.0.0")
:type 'string)
(defcustom denote-after-new-note-hook nil
"Normal hook that runs after the `denote' command.
This also covers all convenience functions that call `denote'
internally, such as `denote-signature' and `denote-type' (check
the default value of the user option `denote-commands-for-new-notes')."
:group 'denote
:package-version '(denote . "2.1.0")
:link '(info-link "(denote) Standard note creation")
:type 'hook)
(defcustom denote-after-rename-file-hook nil
"Normal hook called after a succesful Denote rename operation.
This affects the behaviour of the commands `denote-rename-file',
`denote-dired-rename-files', `denote-rename-file-using-front-matter',
`denote-dired-rename-marked-files-with-keywords',
`denote-dired-rename-marked-files-using-front-matter',
`denote-keywords-add', `denote-keywords-remove', and any other
command that builds on top of them."
:group 'denote
:package-version '(denote . "2.3.0")
:link '(info-link "(denote) Renaming files")
:type 'hook)
(defcustom denote-region-after-new-note-functions nil
"Abnormal hook called after `denote-region'.
Functions in this hook are called with two arguments,
representing the beginning and end buffer positions of the region
that was inserted in the new note. These are called only if
`denote-region' is invoked while a region is active.
A common use-case is to call `org-insert-structure-template'
after a region is inserted. This case does not actually require
the aforementioned arguments, in which case the function can
simply declare them as ignored by prefixing the argument names
with an underscore. For example, the following will prompt for a
structure template as soon as `denote-region' is done:
(defun my-denote-region-org-structure-template (_beg _end)
(when (derived-mode-p \\='org-mode)
(activate-mark)
(call-interactively \\='org-insert-structure-template)))
(add-hook \\='denote-region-after-new-note-functions
#\\='my-denote-region-org-structure-template)"
:group 'denote
:package-version '(denote . "2.1.0")
:link '(info-link "(denote) Create a note with the region's contents")
:type 'hook)
(defvar denote-prompts-with-history-as-completion
'(denote-title-prompt denote-signature-prompt denote-files-matching-regexp-prompt)
"Prompts that conditionally perform completion against their history.
These are minibuffer prompts that ordinarily accept a free form string
input, as opposed to matching against a predefined set.
These prompts can optionally perform completion against their own
minibuffer history when the user option `denote-history-completion-in-prompts'
is set to a non-nil value.")
(defcustom denote-history-completion-in-prompts t
"Toggle history completion in all `denote-prompts-with-history-as-completion'.
When this user option is set to a non-nil value, use minibuffer history
entries as completion candidates in `denote-prompts-with-history-as-completion'.
Those will show previous inputs from their respective history as
possible values to select, either to (i) re-insert them verbatim or (ii)
with the intent to edit further (depending on the minibuffer user
interface, one can select a candidate with TAB without exiting the
minibuffer, as opposed to what RET normally does by selecting and
exiting).
When this user option is set to a nil value, all of the
`denote-prompts-with-history-as-completion' do not use minibuffer
completion: they just prompt for a string of characters. Their
history is still available through all the standard ways of retrieving
minibuffer history, such as with the command `previous-history-element'.
History completion still allows arbitrary values to be provided as
input: they do not have to match the available minibuffer completion
candidates.
Note that some prompts, like `denote-keywords-prompt', always use
minibuffer completion, due to the specifics of their data.
[ Consider enabling the built-in `savehist-mode' to persist minibuffer
histories between sessions.]
Also see `denote-prompts'."
:type 'boolean
:package-version '(denote . "2.3.0")
:group 'denote)
(defcustom denote-commands-for-new-notes
'(denote
denote-date
denote-subdirectory
denote-template
denote-type
denote-signature)
"List of commands for `denote-command-prompt' that create a new note.
These are used by commands such as `denote-open-or-create-with-command'
and `denote-link-after-creating-with-command'."
:group 'denote
:package-version '(denote . "2.1.0")
:link '(info-link "(denote) Choose which commands to prompt for")
:type '(repeat symbol))
(defcustom denote-file-name-slug-functions
'((title . denote-sluggify-title)
(signature . denote-sluggify-signature)
(keyword . denote-sluggify-keyword))
"Specify the method Denote uses to format the components of the file name.
The value is an alist where each element is a cons cell of the
form (COMPONENT . METHOD).
- The COMPONENT is an unquoted symbol among `title', `signature',
`keyword' (notice the absence of `s', see below), which
refers to the corresponding component of the file name.
- The METHOD is the function to be used to format the given
component. This function should take a string as its parameter
and return the string formatted for the file name. In the case
of the `keyword' component, the function receives a SINGLE
string representing a single keyword and return it formatted
for the file name. Joining the keywords together is handled by
Denote.
Note that the `keyword' function is also applied to the keywords
of the front matter.
By default, if a function is not specified for a component, we
use `denote-sluggify-title', `denote-sluggify-keyword' and
`denote-sluggify-signature'.
Remember that deviating from the default file-naming scheme of Denote
will make things harder to search in the future, as files can/will have
permutations that create uncertainty. The sluggification scheme and
concomitant restrictions we impose by default are there for a very good
reason: they are the distillation of years of experience. Here we give
you what you wish, but bear in mind it may not be what you need. You
have been warned."
:group 'denote
:package-version '(denote . "2.3.0")
:link '(info-link "(denote) User-defined sluggification of file name components")
:type '(alist :key (choice (const title)
(const signature)
(const keyword))
:value function))
(make-obsolete
'denote-file-name-letter-casing
'denote-file-name-slug-functions
"2.3.0")
(define-obsolete-variable-alias
'denote-link-button-action
'denote-open-link-function
"3.2.0")
(defcustom denote-open-link-function #'find-file-other-window
"Function to find the file of a Denote link.
The default value is `find-file-other-window', with `find-file' because
another common option. Users can provide a custom function which
behaves like the other two.
This is used in all non-Org buffers that have a link created by Denote.
Org has its own mechanism, which you can learn more about by reading the
documentation of the `org-open-at-point' command."
:group 'denote
:type '(choice (function :tag "Other window" find-file-other-window)
(function :tag "Current window" find-file)
(function :tag "Custom function"))
:package-version '(denote . "3.2.0"))
(define-obsolete-variable-alias
'denote-link-description-function
'denote-link-description-format
"3.2.0")
;; FIXME 2024-11-03: This breaks `denote-link-with-signature'. Check
;; the FIXME above that function to decide how best to proceed.
(defcustom denote-link-description-format #'denote-link-description-with-signature-and-title
"The format of a link description text.
This determines how `denote-link' and related functions create a link
description by default.
The value can be either a function or a string. If it is a function, it
is called with one argument, the file, and should return a string
representing the link description.
The default is a function that returns the active region or the title of
the note (with the signature if present).
If the value is a string, it treats specially the following specifiers:
- The %t is the Denote TITLE in the front matter or the file name.
- The %T is the Denote TITLE in the file name.
- The %i is the Denote IDENTIFIER of the file.
- The %d is the same as %i (DATE mnemonic).
- The %s is the Denote SIGNATURE of the file.
- The %k is the Denote KEYWORDS of the file.
- The %% is a literal percent sign.
In addition, the following flags are available for each of the specifiers:
- 0 :: Pad to the width, if given, with zeros instead of spaces.
- - :: Pad to the width, if given, on the right instead of the left.
- < :: Truncate to the width and precision, if given, on the left.
- > :: Truncate to the width and precision, if given, on the right.
- ^ :: Convert to upper case.
- _ :: Convert to lower case.
When combined all together, the above are written thus:
%<flags><width><precision>SPECIFIER-CHARACTER
Any other text in the string it taken as-is. Users may want, for
example, to include some text that makes Denote links stand out, such as
a [D] prefix.
If the region is active, its text is used as the link's description."
:type '(choice
(string :tag "String with treats format specifiers specially")
(function :tag "Custom function like `denote-link-description-with-signature-and-title'"))
:package-version '(denote . "3.2.0")
:group 'denote)
;;;; Main variables
;; For character classes, evaluate: (info "(elisp) Char Classes")
(defconst denote-id-format "%Y%m%dT%H%M%S"
"Format of ID prefix of a note's filename.
The note's ID is derived from the date and time of its creation.")
(defconst denote-id-regexp "\\([0-9]\\{8\\}\\)\\(T[0-9]\\{6\\}\\)"
"Regular expression to match `denote-id-format'.")
(defconst denote-signature-regexp "==\\([^.]*?\\)\\(==.*\\|--.*\\|__.*\\|@@.*\\|\\..*\\)*$"
"Regular expression to match the SIGNATURE field in a file name.")
(defconst denote-title-regexp "--\\([^.]*?\\)\\(==.*\\|__.*\\|@@.*\\|\\..*\\)*$"
"Regular expression to match the TITLE field in a file name.")
(defconst denote-keywords-regexp "__\\([^.]*?\\)\\(==.*\\|--.*\\|__.*\\|@@.*\\|\\..*\\)*$"
"Regular expression to match the KEYWORDS field in a file name.")
(make-obsolete-variable
'denote-excluded-punctuation-extra-regexp
'denote-file-name-slug-functions
"3.2.0")
;;;; File helper functions
(defun denote--completion-table (category candidates)
"Pass appropriate metadata CATEGORY to completion CANDIDATES."
(lambda (string pred action)
(if (eq action 'metadata)
`(metadata (category . ,category))
(complete-with-action action candidates string pred))))
(defun denote--completion-table-no-sort (category candidates)
"Pass appropriate metadata CATEGORY to completion CANDIDATES.
Like `denote--completion-table' but also disable sorting."
(lambda (string pred action)
(if (eq action 'metadata)
`(metadata (category . ,category)
(display-sort-function . ,#'identity))
(complete-with-action action candidates string pred))))
(defun denote--default-directory-is-silo-p ()
"Return path to silo if `default-directory' is a silo."
(when-let* ((dir-locals (dir-locals-find-file default-directory))
((alist-get 'denote-directory dir-local-variables-alist)))
(cond
((listp dir-locals)