Notes on writing plugins.

Shrikant Sharat
1 parent 72e36b84ea
Showing 1 changed file with 21 additions and 1 deletions Side-by-side Diff
README.mkd
@@ -403,7 +403,27 @@ functionality of antigen.
  
 ## Notes on writing plugins
  
-> *TBD*
+If you are just going to write a single `.sh` file with the goodness you want to
+create, just forget about this and go do that. Antigen will work just find with
+such a plugin.
+
+If you want to know how antigen loads the plugins, do continue.
+
+Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If
+present, it will source *only* this script. Nothing else is sourced.
+
+Otherwise, it looks for `*.zsh` files and if there are any, *all* of them are
+sourced. The order in which they are sourced is not currently defined. Please
+don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts.
+
+If no `*.zsh` files are present, it finally looks for any `*.sh` files and
+sources *all* of them. Again, the order in which they are sourced in not
+currently defined.
+
+No matter which (or none) of the above happen to be sourced, this plugin
+directory is added to the zsh's function path (`$fpath`) so that any completions
+in it are loaded. One exception to this rule is that if this plugin is a prompt
+theme. In which case the theme script is just sourced and nothing else is done.
  
 ## Meta
...	...	@@ -403,7 +403,27 @@ functionality of antigen.
403	403
404	404	## Notes on writing plugins
405	405
406		-> TBD
	406	+If you are just going to write a single `.sh` file with the goodness you want to
	407	+create, just forget about this and go do that. Antigen will work just find with
	408	+such a plugin.
	409	+
	410	+If you want to know how antigen loads the plugins, do continue.
	411	+
	412	+Firstly, antigen looks for a `*.plugin.zsh` file in the plugin directory. If
	413	+present, it will source only this script. Nothing else is sourced.
	414	+
	415	+Otherwise, it looks for `.zsh` files and if there are any, all* of them are
	416	+sourced. The order in which they are sourced is not currently defined. Please
	417	+don't rely on this order. Nothing else is sourced after all the `*.zsh` scripts.
	418	+
	419	+If no `.zsh` files are present, it finally looks for any `.sh` files and
	420	+sources all of them. Again, the order in which they are sourced in not
	421	+currently defined.
	422	+
	423	+No matter which (or none) of the above happen to be sourced, this plugin
	424	+directory is added to the zsh's function path (`$fpath`) so that any completions
	425	+in it are loaded. One exception to this rule is that if this plugin is a prompt
	426	+theme. In which case the theme script is just sourced and nothing else is done.
407	427
408	428	## Meta
409	429