doomemacs/modules/editor/file-templates/README.org

# -*- mode: doom-docs-org -*-
#+title:    :editor file-templates
#+subtitle: Fill the void in your empty files
#+created:  February 11, 2017
#+since:    2.0.0

* Description :unfold:
This module adds file templates for blank files, powered by [[doom-package:][yasnippet]].

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
/This module doesn't install any packages./

** Hacks
- [[doom-package:][yasnippet]]

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

/This module has no external requirements./

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

File templates are automatically expanded when opening empty files who match one
of the rules in the ~+file-templates-alist~ variable.

These templates are simply yasnippet snippets, which can also be expanded by
typing their trigger and pressing [[kbd:][TAB]]. By convention, the triggers for file
templates are prefixed with two underscores ~__~ (the trigger for the default
file template of a major mode is almost always ~__~).

** Inserting OSS licenses
A special command is available for inserting software licenses: ~M-x
+file-templates/insert-license~.

#+begin_quote
 📌 Licenses with a ~-bp~ suffix are boilerplate templates; i.e. shorter
    versions intended for comment headers in code files.
#+end_quote

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Adding new or changing existing file templates
New file templates can be added to
=$DOOMDIR/snippets/{major-mode}/{snippet-name}=. The yasnippet documentation
covers [[https://joaotavora.github.io/yasnippet/snippet-development.html][how to write a snippet]]. You can map a snippet to a file path, major mode,
or another arbitrary predicate using [[fn:][set-file-template!]].

Look into its documentation with [[kbd:][<help> f set-file-template\!]].

** Adding new OSS licenses
Add snippet files to =$DOOMDIR/snippets/text-mode/= with the =__licenses-=
prefix and [[fn:][+file-templates/insert-license]] will recognize them. E.g.
=$DOOMDIR/snippets/text-mode/__license-mit=.

* Troubleshooting
- If a file template isn't expanding where you expect it to, run ~M-x
  +file-templates/debug~. This will report to you what file template rule would
  apply for the correct file.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote

** API
- ~set-file-template! PRED &rest PLIST~
- ~set-file-templates! &rest TEMPLATES~

** Commands
- ~+file-templates/insert-license~
- ~+file-templates/debug~

** Variables
- ~+file-templates-dir~
- ~+file-templates-default-trigger~
- ~+file-templates-alist~