merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,48 +1,28 @@
|
|||
#+TITLE: lang/org
|
||||
#+DATE: February 19, 2017
|
||||
#+SINCE: 2.0
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :lang org
|
||||
#+subtitle: Organize your plain life in plain text
|
||||
#+created: February 20, 2017
|
||||
#+since: 2.0.0
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#hacks][Hacks]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#macos][MacOS]]
|
||||
- [[#arch-linux][Arch Linux]]
|
||||
- [[#nixos][NixOS]]
|
||||
- [[#windows][Windows]]
|
||||
- [[#features][Features]]
|
||||
- [[#invoking-the-org-capture-frame-from-outside-emacs][Invoking the org-capture frame from outside Emacs]]
|
||||
- [[#built-in-custom-link-types][Built-in custom link types]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#changing-org-directory][Changing ~org-directory~]]
|
||||
- [[#changing-org-noter-notes-search-path][Changing ~org-noter-notes-search-path~]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
- [[#org-roam][=org-roam=]]
|
||||
- [[#should-i-go-with-roam-v1-or-roam2-v2][Should I go with =+roam= (v1) or =+roam2= (v2)?]]
|
||||
- [[#migrating-your-existing-files-from-v1-roam-to-v2-roam2][Migrating your existing files from v1 (=+roam=) to v2 (=+roam2=)]]
|
||||
|
||||
* Description
|
||||
* Description :unfold:
|
||||
This module adds org-mode support to Doom Emacs, along with a number of
|
||||
adjustments, extensions and reasonable defaults to make it more performant and
|
||||
intuitive out of the box:
|
||||
|
||||
+ A custom, centralized attachment system that stores files in one place, rather
|
||||
- A custom, centralized attachment system that stores files in one place, rather
|
||||
than in the same directory as the input file(s) (only applies to attachments
|
||||
from files in/under =org-directory=).
|
||||
+ Executable code blocks with support for a variety of languages and tools
|
||||
from files in/under ~org-directory~).
|
||||
- Executable code blocks with support for a variety of languages and tools
|
||||
(depending on what :lang modules are enabled).
|
||||
+ Supports an external org-capture workflow through the =bin/org-capture= shell
|
||||
- Supports an external org-capture workflow through the =bin/org-capture= shell
|
||||
script and ~+org-capture/open-frame~.
|
||||
+ A configuration for using org-mode for slide-show presentations or exporting
|
||||
- A configuration for using org-mode for slide-show presentations or exporting
|
||||
org files to reveal.js slideshows.
|
||||
+ Drag-and-drop support for images (with inline preview) and media files (drops
|
||||
a file icon and a short link) (requires =+dragndrop= flag).
|
||||
+ Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others
|
||||
- Drag-and-drop support for images (with inline preview) and media files (drops
|
||||
a file icon and a short link) (requires [[doom-module:][+dragndrop]] flag).
|
||||
- Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others
|
||||
(requires flags).
|
||||
+ Export-to-clipboard functionality, for copying text into formatted html,
|
||||
- Export-to-clipboard functionality, for copying text into formatted html,
|
||||
markdown or rich text to the clipboard (see ~+org/export-to-clipboard~ and
|
||||
~+org/export-to-clipboard-as-rich-text~).
|
||||
|
||||
|
|
@ -56,218 +36,231 @@ executed.
|
|||
https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/
|
||||
#+end_quote
|
||||
|
||||
** Module Flags
|
||||
+ =+brain= Enables [[https://github.com/Kungsgeten/org-brain][org-brain]] integration.
|
||||
+ =+dragndrop= Enables drag-and-drop support for images and files; inserts
|
||||
inline previews for images and an icon+link for other media types.
|
||||
+ =+gnuplot= Installs gnuplot & gnuplot-mode, which enables rendering images
|
||||
from gnuplot src blocks or plotting tables with ~org-plot/gnuplot~ (bound to
|
||||
=SPC m b p=, by default).
|
||||
+ =+hugo= Enables integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed
|
||||
([[https://github.com/russross/blackfriday][blackfriday]]) markdown.
|
||||
+ =+ipython= (**DEPRECATED**) Enables ipython integration for babel.
|
||||
+ =+journal= Enables [[https://github.com/bastibe/org-journal][org-journal]] integration.
|
||||
+ =+jupyter= Enables Jupyter integration for babel.
|
||||
+ =+noter= Enables org-noter integration. Keeps notes in sync with a document.
|
||||
Requires [[https://github.com/politza/pdf-tools][pdf-tools]] (=:tools pdf=) or [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]] or [[https://github.com/wasamasa/nov.el][nov.el]] to be enabled.
|
||||
+ =+pandoc= Enables pandoc integration into the Org exporter.
|
||||
+ =+pomodoro= Enables a pomodoro timer for clocking time on tasks.
|
||||
+ =+present= Enables integration with reveal.js, beamer and org-tree-slide, so
|
||||
Emacs can be used for presentations. It automatically downloads [[https://github.com/hakimel/reveal.js][reveal.js]].
|
||||
+ =+pretty= Enables pretty unicode symbols for bullets and priorities, and
|
||||
better syntax highlighting for latex. Keep in mind: this can be expensive. If
|
||||
org becomes too slow, it'd be wise to disable this flag.
|
||||
+ =+roam= Enables integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be
|
||||
installed on your system. Incompatible with =+roam2=.
|
||||
+ =+roam2= Enables integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be
|
||||
installed on your system. Incompatible with =+roam=.
|
||||
** Maintainers
|
||||
- [[doom-user:][@hlissner]]
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/hniksic/emacs-htmlize][htmlize]]
|
||||
+ [[https://github.com/astahlman/ob-async][ob-async]]
|
||||
+ [[https://github.com/rexim/org-cliplink][org-cliplink]]
|
||||
+ [[https://github.com/magit/orgit][orgit]]
|
||||
+ [[https://orgmode.org/][org-plus-contrib]]
|
||||
+ [[https://github.com/TobiasZawada/org-yt][org-yt]]
|
||||
+ [[https://github.com/jkitchin/ox-clip][ox-clip]]
|
||||
+ [[https://github.com/snosov1/toc-org][toc-org]]
|
||||
+ =:lang crystal=
|
||||
+ [[https://github.com/brantou/ob-crystal][ob-crystal]]
|
||||
+ =:lang go=
|
||||
+ [[https://github.com/pope/ob-go][ob-go]]
|
||||
+ =:lang nim=
|
||||
+ [[https://github.com/Lompik/ob-nim][ob-nim]]
|
||||
+ =:lang racket=
|
||||
+ [[https://github.com/DEADB17/ob-racket][ob-racket]]
|
||||
+ =:lang rest=
|
||||
+ [[https://github.com/alf/ob-restclient.el][ob-restclient]]
|
||||
+ =:lang rst=
|
||||
+ [[https://github.com/msnoigrs/ox-rst][ox-rst]]
|
||||
+ =:lang rust=
|
||||
+ [[https://github.com/micanzhang/ob-rust][ob-rust]]
|
||||
+ =:lang scala=
|
||||
+ [[https://github.com/zwild/ob-ammonite][ob-ammonite]]
|
||||
+ =:editor evil=
|
||||
+ [[https://github.com/Somelauw/evil-org-mode][evil-org]]
|
||||
+ =:tools pdf=
|
||||
+ [[https://github.com/fuxialexander/org-pdftools][org-pdftools]]
|
||||
+ =+dragndrop=
|
||||
+ [[https://github.com/abo-abo/org-download][org-download]]
|
||||
+ =+gnuplot=
|
||||
+ [[https://github.com/mkmcc/gnuplot-mode][gnuplot]]
|
||||
+ [[https://github.com/bruceravel/gnuplot-mode][gnuplot-mode]]
|
||||
+ =+hugo=
|
||||
+ [[https://github.com/kaushalmodi/ox-hugo][ox-hugo]]
|
||||
+ =+ipython=
|
||||
+ [[https://github.com/gregsexton/ob-ipython][ob-ipython]]
|
||||
+ =+jupyter=
|
||||
+ [[https://github.com/dzop/emacs-jupyter][jupyter]]
|
||||
+ =+pandoc=
|
||||
+ [[https://github.com/kawabata/ox-pandoc][ox-pandoc]]
|
||||
+ =+pomodoro=
|
||||
+ [[https://github.com/marcinkoziej/org-pomodoro][org-pomodoro]]
|
||||
+ =+present=
|
||||
+ [[https://github.com/anler/centered-window-mode][centered-window]]
|
||||
+ [[https://github.com/takaxp/org-tree-slide][org-tree-slide]]
|
||||
+ [[https://gitlab.com/oer/org-re-reveal][org-re-reveal]]
|
||||
+ =+pretty=
|
||||
+ [[https://github.com/integral-dw/org-superstar-mode][org-superstar]]
|
||||
+ [[https://github.com/harrybournis/org-fancy-priorities][org-fancy-priorities]]
|
||||
+ =+roam=
|
||||
+ [[https://github.com/org-roam/org-roam-v1][org-roam]] (v1)
|
||||
+ =+roam2=
|
||||
- [[https://github.com/org-roam/org-roam][org-roam]] (v2)
|
||||
+ =+noter=
|
||||
+ [[https://github.com/weirdNox/org-noter][org-noter]]
|
||||
[[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** Module flags
|
||||
- +brain ::
|
||||
Enable [[https://github.com/Kungsgeten/org-brain][org-brain]] integration.
|
||||
- +dragndrop ::
|
||||
Enable drag-and-drop support for images and files; inserts inline previews
|
||||
for images and an icon+link for other media types.
|
||||
- +gnuplot ::
|
||||
Install gnuplot & gnuplot-mode, which enables rendering images from gnuplot
|
||||
src blocks or plotting tables with ~org-plot/gnuplot~ (bound to =SPC m b p=,
|
||||
by default).
|
||||
- +hugo ::
|
||||
Enable integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed ([[https://github.com/russross/blackfriday][blackfriday]])
|
||||
markdown.
|
||||
- +ipython ::
|
||||
(**DEPRECATED**) Enable ipython integration for babel.
|
||||
- +journal ::
|
||||
Enable [[doom-package:][org-journal]] integration.
|
||||
- +jupyter ::
|
||||
Enable Jupyter integration for babel.
|
||||
- +noter ::
|
||||
Enable [[doom-package:][org-noter]] integration. Keeps notes in sync with a document. Requires
|
||||
[[doom-module:][:tools pdf]], [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]], or [[https://github.com/wasamasa/nov.el][nov.el]] to be enabled.
|
||||
- +pandoc ::
|
||||
Enable pandoc integration into the Org exporter.
|
||||
- +pomodoro ::
|
||||
Enable a pomodoro timer for clocking time on tasks.
|
||||
- +present ::
|
||||
Enable integration with reveal.js, beamer and org-tree-slide, so Emacs can be
|
||||
used for presentations. It automatically downloads [[https://github.com/hakimel/reveal.js][reveal.js]].
|
||||
- +pretty ::
|
||||
Enable pretty unicode symbols for bullets+priorities and better syntax
|
||||
highlighting for latex. Keep in mind: this can be expensive. If org becomes
|
||||
too slow, it'd be wise to disable this flag.
|
||||
- +roam ::
|
||||
Enable integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be installed
|
||||
on your system. /Incompatible with [[doom-module:][+roam2]]./
|
||||
- +roam2 ::
|
||||
Enable integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be installed
|
||||
on your system. /Incompatible with [[doom-module:][+roam]]./
|
||||
|
||||
** Packages
|
||||
- [[doom-package:][evil-org]] if [[doom-package:][:editor evil]]
|
||||
- [[doom-package:][htmlize]]
|
||||
- [[doom-package:][jupyter]] if [[doom-package:][+jupyter]]
|
||||
- [[doom-package:][ob-ammonite]] if [[doom-package:][:lang scala]]
|
||||
- [[doom-package:][ob-async]]
|
||||
- [[doom-package:][ob-crystal]] if [[doom-package:][:lang crystal]]
|
||||
- [[doom-package:][ob-go]] if [[doom-package:][:lang go]]
|
||||
- [[doom-package:][ob-ipython]] if [[doom-package:][+ipython]]
|
||||
- [[doom-package:][ob-nim]] if [[doom-package:][:lang nim]]
|
||||
- [[doom-package:][ob-racket]] if [[doom-package:][:lang racket]]
|
||||
- [[doom-package:][ob-restclient]] if [[doom-package:][:lang rest]]
|
||||
- [[doom-package:][ob-rust]] if [[doom-package:][:lang rust]]
|
||||
- [[doom-package:][org-cliplink]]
|
||||
- [[doom-package:][org-download]] if [[doom-package:][+dragndrop]]
|
||||
- [[doom-package:][orgit]]
|
||||
- [[doom-package:][org-noter]] if [[doom-package:][+noter]]
|
||||
- [[doom-package:][org-pdftools]] if [[doom-package:][:tools pdf]]
|
||||
- [[doom-package:][org-plus-contrib]]
|
||||
- [[doom-package:][org-pomodoro]] if [[doom-package:][+pomodoro]]
|
||||
- [[doom-package:][org-roam]] (v1) if [[doom-package:][+roam]]
|
||||
- [[doom-package:][org-roam]] (v2) if [[doom-package:][+roam2]]
|
||||
- [[doom-package:][org-yt]]
|
||||
- [[doom-package:][ox-clip]]
|
||||
- [[doom-package:][ox-hugo]] if [[doom-package:][+hugo]]
|
||||
- [[doom-package:][ox-pandoc]] if [[doom-package:][+pandoc]]
|
||||
- [[doom-package:][ox-rst]] if [[doom-package:][:lang rst]]
|
||||
- [[doom-package:][toc-org]]
|
||||
- if [[doom-package:][+gnuplot]]
|
||||
- [[doom-package:][gnuplot]]
|
||||
- [[doom-package:][gnuplot-mode]]
|
||||
- if [[doom-package:][+present]]
|
||||
- [[doom-package:][centered-window]]
|
||||
- [[doom-package:][org-tree-slide]]
|
||||
- [[doom-package:][org-re-reveal]]
|
||||
- if [[doom-package:][+pretty]]
|
||||
- [[doom-package:][org-superstar]]
|
||||
- [[doom-package:][org-fancy-priorities]]
|
||||
|
||||
** Hacks
|
||||
+ Adds support for a ~:sync~ parameter for org src blocks. This overrides
|
||||
- Adds support for a ~:sync~ parameter for org src blocks. This overrides
|
||||
~:async~.
|
||||
+ Gracefully degrades ~:async~ babel blocks to ~:sync~ when =ob-async= would
|
||||
cause errors or issues (such as with a ~:session~ parameter, which =ob-async=
|
||||
does not support, or when exporting org documents).
|
||||
+ The window is recentered when following links.
|
||||
+ The breadcrumbs displayed in eldoc when hovering over an org headline has been
|
||||
- Gracefully degrades ~:async~ babel blocks to ~:sync~ when [[doom-package:][ob-async]] would cause
|
||||
errors or issues (such as with a ~:session~ parameter, which [[doom-package:][ob-async]] does not
|
||||
support, or when exporting org documents).
|
||||
- The window is recentered when following links.
|
||||
- The breadcrumbs displayed in eldoc when hovering over an org headline has been
|
||||
reworked to strip out link syntax and normalize font-size disparities.
|
||||
+ If =:ui workspaces= is enabled, persp-mode won't register org agenda buffers that
|
||||
are temporarily opened in the background.
|
||||
+ Temporary org agenda files aren't added to recentf.
|
||||
+ =file:= links are highlighted with the ~error~ face if they are broken.
|
||||
+ TAB was changed to toggle only the visibility state of the current subtree,
|
||||
- If [[doom-module:][:ui workspaces]] is enabled, persp-mode won't register org agenda buffers
|
||||
that are temporarily opened in the background.
|
||||
- Temporary org agenda files aren't added to recentf.
|
||||
- =file:= links are highlighted with the ~error~ face if they are broken.
|
||||
- TAB was changed to toggle only the visibility state of the current subtree,
|
||||
rather than cycle through it recursively. This can be reversed with:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
#+begin_src emacs-lisp
|
||||
(after! evil-org
|
||||
(remove-hook 'org-tab-first-hook #'+org-cycle-only-current-subtree-h))
|
||||
#+END_SRC
|
||||
+ (Evil users) Nearby tables are formatted when exiting insert or replace mode
|
||||
#+end_src
|
||||
- (Evil users) Nearby tables are formatted when exiting insert or replace mode
|
||||
(see ~+org-enable-auto-reformat-tables-h~).
|
||||
+ Statistics cookies are updated when saving the buffer of exiting insert mode
|
||||
- Statistics cookies are updated when saving the buffer of exiting insert mode
|
||||
(see ~+org-enable-auto-update-cookies-h~).
|
||||
+ Org-protocol has been lazy loaded (see ~+org-init-protocol-lazy-loader-h~);
|
||||
- Org-protocol has been lazy loaded (see ~+org-init-protocol-lazy-loader-h~);
|
||||
loaded when the server receives a request for an org-protocol:// url.
|
||||
+ Babel and babel plugins are now lazy loaded (see
|
||||
- Babel and babel plugins are now lazy loaded (see
|
||||
~+org-init-babel-lazy-loader-h~); loaded when a src block is executed. No need
|
||||
to use ~org-babel-do-load-languages~ in your config, just install your babel
|
||||
packages to extend language support (and ensure its ~org-babel-execute:*~
|
||||
function is autoloaded).
|
||||
+ If a variable is used as a file path in ~org-capture-template~, it will be
|
||||
- If a variable is used as a file path in ~org-capture-template~, it will be
|
||||
resolved relative to ~org-directory~, instead of ~default-directory~ (see
|
||||
~+org-capture-expand-variable-file-a~).
|
||||
|
||||
* Prerequisites
|
||||
Org has a few soft dependencies that you will need to make use of Org's more
|
||||
esoteric features:
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
+ For inline LaTeX previews, ~latex~ and ~dvipng~ is needed.
|
||||
+ To render GNUPlot images (with =+gnuplot= flag) the ~gnuplot~ program is
|
||||
needed.
|
||||
+ To execute babel code blocks, you need whatever dependencies those languages
|
||||
need. It is recommended you enable the associated =:lang= module and ensure
|
||||
its dependencies are met, e.g. install the =ruby= executable for ruby support.
|
||||
To use ~jupyter kernels~ you need the =+jupyter= flag, the associated kernel as
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
This module has no hard requirements, but these soft requirements are needed to
|
||||
use Org's more esoteric features:
|
||||
- For inline LaTeX previews, ~latex~ and ~dvipng~ is needed.
|
||||
- To render GNUPlot images (with [[doom-module:][+gnuplot]] flag) the ~gnuplot~ program is needed.
|
||||
- To execute babel code blocks, you need whatever dependencies those languages
|
||||
need. It is recommended you enable the associated [[doom-module:][:lang]] module and ensure its
|
||||
dependencies are met, e.g. install the =ruby= executable for ruby support. To
|
||||
use ~jupyter kernels~ you need the [[doom-module:][+jupyter]] flag, the associated kernel as
|
||||
well as the ~jupyter~ program.
|
||||
+ =org-roam= (with =+roam= or =+roam2= flag) requires =sqlite3= to be installed.
|
||||
- [[doom-package:][org-roam]] (with [[doom-module:][+roam]] or [[doom-module:][+roam2]] flag) requires =sqlite3= to be installed.
|
||||
|
||||
** MacOS
|
||||
#+BEGIN_SRC sh
|
||||
#+begin_src sh
|
||||
brew install --cask mactex
|
||||
brew install gnuplot
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** Arch Linux
|
||||
#+BEGIN_SRC sh
|
||||
pacman -S texlive-core texlive-bin texlive-science
|
||||
#+begin_src sh
|
||||
pacman -S texlive-core texlive-bin texlive-science texlive-latexextra
|
||||
pacman -S gnuplot
|
||||
pacman -S jupyter # required by +jupyter
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** NixOS
|
||||
#+BEGIN_SRC nix
|
||||
#+begin_src nix
|
||||
environment.systemPackages = with pkgs; [
|
||||
# any less than medium isn't guaranteed to work
|
||||
texlive.combined.scheme-medium
|
||||
# required by +jupyter
|
||||
(python38.withPackages(ps: with ps; [jupyter]))
|
||||
];
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** TODO Windows
|
||||
|
||||
* Features
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
** Invoking the org-capture frame from outside Emacs
|
||||
The simplest way to use the org-capture frame is through the ~bin/org-capture~
|
||||
script. I'd recommend binding a shortcut key to it. If Emacs isn't running, it
|
||||
will spawn a temporary daemon for you.
|
||||
|
||||
Alternatively, you can call ~+org-capture/open-frame~ directly, e.g.
|
||||
|
||||
#+BEGIN_SRC sh
|
||||
emacsclient --eval '(+org-capture/open-frame INTIAL-INPUT KEY)'
|
||||
#+END_SRC
|
||||
#+begin_src sh
|
||||
emacsclient --eval '(+org-capture/open-frame INITIAL-INPUT KEY)'
|
||||
#+end_src
|
||||
|
||||
** Built-in custom link types
|
||||
This module defines a number of custom link types in ~+org-init-custom-links-h~.
|
||||
They are (with examples):
|
||||
|
||||
+ ~doom-docs:news/2.1.0~ (=~/.emacs.d/docs/%s=)
|
||||
+ ~doom-modules:editor/evil/README.org~ (=~/.emacs.d/modules/%s=)
|
||||
+ ~doom-repo:issues~ (=https://github.com/hlissner/doom-emacs/%s=)
|
||||
+ ~doom:core/core.el~ (=~/.emacs.d/%s=)
|
||||
+ ~duckduckgo:search terms~
|
||||
+ ~gimages:search terms~ (Google Images)
|
||||
+ ~github:hlissner/doom-emacs~
|
||||
+ ~gmap:Toronto, Ontario~ (Google Maps)
|
||||
+ ~google:search terms~
|
||||
+ ~org:todo.org~ (={org-directory}/%s=)
|
||||
+ ~wolfram:sin(x^3)~
|
||||
+ ~wikipedia:Emacs~
|
||||
+ ~youtube:P196hEuA_Xc~ (link only)
|
||||
+ ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video)
|
||||
- ~doom-docs:index.org~ -> =~/.emacs.d/docs/%s=
|
||||
- ~doom-modules:editor/evil/README.org~ -> =~/.emacs.d/modules/%s=
|
||||
- ~doom-repo:issues~ -> =https://github.com/hlissner/doom-emacs/%s=
|
||||
- ~doom:core/core.el~ -> =~/.emacs.d/%s=
|
||||
- ~duckduckgo:search terms~
|
||||
- ~gimages:search terms~ (Google Images)
|
||||
- ~github:hlissner/doom-emacs~
|
||||
- ~gmap:Toronto, Ontario~ (Google Maps)
|
||||
- ~google:search terms~
|
||||
- ~org:todo.org~ -> ={org-directory}/%s=
|
||||
- ~wolfram:sin(x^3)~
|
||||
- ~wikipedia:Emacs~
|
||||
- ~youtube:P196hEuA_Xc~ (link only)
|
||||
- ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video)
|
||||
|
||||
** evil-mode keybindings
|
||||
For =evil-mode= users, an overview of org-mode keybindings is provided [[https://github.com/Somelauw/evil-org-mode/blob/master/README.org#keybindings][here]].
|
||||
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
* Configuration
|
||||
** Changing ~org-directory~
|
||||
To modify ~org-directory~ it must be set /before/ =org= has loaded:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
;; ~/.doom.d/config.el
|
||||
~org-directory~ must be set /before/ [[doom-package:][org]] has loaded:
|
||||
#+begin_src emacs-lisp
|
||||
;; in $DOOMDIR/config.el
|
||||
(setq org-directory "~/new/org/location/")
|
||||
#+END_SRC
|
||||
** Changing ~org-noter-notes-search-path~
|
||||
To modify ~org-noter-notes-search-path~ set:
|
||||
#+end_src
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
;; ~/.doom.d/config.el
|
||||
** Changing ~org-noter-notes-search-path~
|
||||
#+begin_src emacs-lisp
|
||||
;; in $DOOMDIR/config.el
|
||||
(setq org-noter-notes-search-path '("~/notes/path/"))
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
* Troubleshooting
|
||||
[[doom-report:][Report an issue?]]
|
||||
|
||||
** =org-roam=
|
||||
*** Should I go with =+roam= (v1) or =+roam2= (v2)?
|
||||
Long story short: if you're new to =org-roam= and haven't used it, then you
|
||||
should go with =+roam2=; if you already have an ~org-roam-directory~ with the v1
|
||||
files in it, then you can keep use =+roam= for a time being.
|
||||
Long story short: if you're new to [[doom-package:][org-roam]] and haven't used it, then you should
|
||||
go with [[doom-module:][+roam2]]; if you already have an ~org-roam-directory~ with the v1 files in
|
||||
it, then you can keep use [[doom-module:][+roam]] for a time being.
|
||||
|
||||
V1 isn't actively maintained anymore and is now basically EOL. This means that
|
||||
the feature disparity between the both will continue to grow, while its existing
|
||||
|
|
@ -291,14 +284,22 @@ appear during the migration process. Because of that, *don't forget to backup*
|
|||
your ~org-roam-directory~ before attempting to migrate.
|
||||
|
||||
In order to migrate from v1 to v2 using Doom follow the next steps:
|
||||
1. Enable =+roam2= flag (and disable =+roam= if it was previously enabled) in
|
||||
your =init.el=.
|
||||
1. Enable [[doom-module:][+roam2]] flag (and disable [[doom-module:][+roam]] if it was previously enabled) in your
|
||||
=init.el=.
|
||||
2. Ensure your ~org-roam-directory~ points to a directory with your v1 files.
|
||||
3. Run =doom sync -u= in your shell.
|
||||
3. Run ~$ doom sync -u~ in your shell.
|
||||
4. Restart Emacs (if it was previously opened) and run ~org-roam-migrate-wizard~
|
||||
command (=M-x org-roam-migrate-wizard RET=). The wizard will automatically
|
||||
command (~M-x org-roam-migrate-wizard RET~). The wizard will automatically
|
||||
attempt to backup your previous ~org-roam-directory~ to =org-roam.bak=, but
|
||||
just in case backup it yourself too.
|
||||
4. After the wizard is done you should be good to go. Verify the integrity of
|
||||
your data and whether it did everything as expected. In case of failure
|
||||
[[https://github.com/org-roam/org-roam/issues][report]] your issue.
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||||
#+end_quote
|
||||
|
|
|
|||
|
|
@ -9,19 +9,6 @@
|
|||
(let ((file (funcall (or fn #'read-file-name) (format "%s: " (capitalize key)) dir)))
|
||||
(format "%s:%s" key (file-relative-name file dir))))
|
||||
|
||||
;;;###autoload
|
||||
(defun +org-read-link-description-at-point (&optional default context)
|
||||
"TODO"
|
||||
(if (and (stringp default) (not (string-empty-p default)))
|
||||
(string-trim default)
|
||||
(if-let* ((context (or context (org-element-context)))
|
||||
(context (org-element-lineage context '(link) t))
|
||||
(beg (org-element-property :contents-begin context))
|
||||
(end (org-element-property :contents-end context)))
|
||||
(unless (= beg end)
|
||||
(replace-regexp-in-string
|
||||
"[ \n]+" " " (string-trim (buffer-substring-no-properties beg end)))))))
|
||||
|
||||
;;;###autoload
|
||||
(defun +org-define-basic-link (key dir-var &rest plist)
|
||||
"Define a link with some basic completion & fontification.
|
||||
|
|
@ -166,83 +153,3 @@ exist, and `org-link' otherwise."
|
|||
(user-error "Not in org-mode"))
|
||||
(or (+org-play-gif-at-point-h)
|
||||
(user-error "No gif at point")))
|
||||
|
||||
|
||||
;;
|
||||
;;; Org-link parameters
|
||||
|
||||
;;; doom-module:
|
||||
(defun +org-link--doom-module--read-link (link)
|
||||
(cl-destructuring-bind (category &optional module flag)
|
||||
(let ((desc (+org-read-link-description-at-point link)))
|
||||
(if (string-prefix-p "+" (string-trim-left desc))
|
||||
(list nil nil (intern desc))
|
||||
(mapcar #'intern (split-string desc " " nil))))
|
||||
(list :category category
|
||||
:module module
|
||||
:flag flag)))
|
||||
|
||||
;;;###autoload
|
||||
(defun +org-link--doom-module-follow-fn (link)
|
||||
(cl-destructuring-bind (&key category module flag)
|
||||
(+org-link--doom-module--read-link link)
|
||||
(when category
|
||||
(let ((doom-modules-dirs (list doom-modules-dir)))
|
||||
(if-let* ((path (doom-module-locate-path category module))
|
||||
(path (or (car (doom-glob path "README.org"))
|
||||
path)))
|
||||
(find-file path)
|
||||
(user-error "Can't find Doom module '%s'" link))))
|
||||
(when flag
|
||||
(goto-char (point-min))
|
||||
(and (re-search-forward "^\\*+ \\(?:TODO \\)?Module Flags")
|
||||
(re-search-forward (format "^\\s-*- %s :: "
|
||||
(regexp-quote (symbol-name flag)))
|
||||
(save-excursion (org-get-next-sibling)
|
||||
(point)))
|
||||
(recenter)))))
|
||||
|
||||
;;;###autoload
|
||||
(defun +org-link--doom-module-face-fn (link)
|
||||
(cl-destructuring-bind (&key category module flag)
|
||||
(+org-link--doom-module--read-link link)
|
||||
(if (doom-module-locate-path category module)
|
||||
`(:inherit org-priority
|
||||
:weight bold)
|
||||
'error)))
|
||||
|
||||
|
||||
;;; doom-package:
|
||||
;;;###autoload
|
||||
(defun +org-link--doom-package-follow-fn (link)
|
||||
"TODO"
|
||||
(doom/describe-package
|
||||
(intern-soft
|
||||
(+org-read-link-description-at-point link))))
|
||||
|
||||
|
||||
;;; kbd:
|
||||
|
||||
(defun +org--describe-kbd (keystr)
|
||||
(dolist (key `(("<leader>" . ,doom-leader-key)
|
||||
("<localleader>" . ,doom-localleader-key)
|
||||
("<prefix>" . ,(if (bound-and-true-p evil-mode)
|
||||
(concat doom-leader-key " u")
|
||||
"C-u"))
|
||||
("<help>" . ,(if (bound-and-true-p evil-mode)
|
||||
(concat doom-leader-key " h")
|
||||
"C-h"))
|
||||
("\\<M-" . "alt-")
|
||||
("\\<S-" . "shift-")
|
||||
("\\<s-" . "super-")
|
||||
("\\<C-" . "ctrl-")))
|
||||
(setq keystr
|
||||
(replace-regexp-in-string (car key) (cdr key)
|
||||
keystr t t)))
|
||||
keystr)
|
||||
|
||||
;;;###autoload
|
||||
(defun +org-read-kbd-at-point (&optional default context)
|
||||
"TODO"
|
||||
(+org--describe-kbd
|
||||
(+org-read-link-description-at-point default context)))
|
||||
|
|
|
|||
|
|
@ -188,21 +188,6 @@ Is relative to `org-directory', unless it is absolute. Is used in Doom's default
|
|||
(when-let* ((context (org-element-context))
|
||||
(path (org-element-property :path context)))
|
||||
(pcase (org-element-property :type context)
|
||||
("kbd"
|
||||
(format "%s %s"
|
||||
(propertize "Key sequence:" 'face 'bold)
|
||||
(propertize (+org-read-kbd-at-point path context)
|
||||
'face 'help-key-binding)))
|
||||
("doom-module"
|
||||
(format "%s %s"
|
||||
(propertize "Doom module:" 'face 'bold)
|
||||
(propertize (+org-read-link-description-at-point path)
|
||||
'face 'org-priority)))
|
||||
("doom-package"
|
||||
(format "%s %s"
|
||||
(propertize "Doom package:" 'face 'bold)
|
||||
(propertize (+org-read-link-description-at-point path)
|
||||
'face 'org-priority)))
|
||||
(type (format "Link: %s" (org-element-property :raw-link context))))))
|
||||
|
||||
;; Automatic indent detection in org files is meaningless
|
||||
|
|
@ -544,7 +529,9 @@ relative to `org-directory', unless it is an absolute path."
|
|||
'("duckduckgo" . "https://duckduckgo.com/?q=%s")
|
||||
'("wikipedia" . "https://en.wikipedia.org/wiki/%s")
|
||||
'("wolfram" . "https://wolframalpha.com/input/?i=%s")
|
||||
'("doom-repo" . "https://github.com/hlissner/doom-emacs/%s"))
|
||||
'("doom" . "https://github.com/hlissner/doom-emacs/%s")
|
||||
`("emacsdir" . ,(doom-path doom-emacs-dir "%s"))
|
||||
`("doomdir" . ,(doom-path doom-private-dir "%s")))
|
||||
|
||||
(+org-define-basic-link "org" 'org-directory)
|
||||
(+org-define-basic-link "doom" 'doom-emacs-dir)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue