Merge 0de305a9a3 into 9d5f5abef4

CHANGELOG.md

@@ -21,6 +21,16 @@ completed.
   - Using this also brings enhancements to the `doc` command like easy
   navigation of neighboring doc files.
 
+### Changed
+- Documentation for EVERYTHING has been improved, with more
+information added, code example, parameter details, etc.
+You can see the improvements!
+- Documentation has gotten an uplift in the `doc` command.
+This includes:
+  - Proper highlighting of code
+  - Paging (via Greenhouse)
+  - Highlighting more markdown things
+
 ### Fixed
 - Fix infinite loop when navigating history without any history. [#252](https://github.com/Rosettea/Hilbish/issues/252)
 - Return the prefix when calling `hilbish.completions.call`. [#219](https://github.com/Rosettea/Hilbish/issues/219)

cmd/docgen/docgen.go

@@ -554,11 +554,11 @@ func main() {
 
 `, htmlSig, dps.FuncName))
 					for _, doc := range dps.Doc {
-						if !strings.HasPrefix(doc, "---") {
+						if !strings.HasPrefix(doc, "---") && doc != "" {
 							f.WriteString(doc + "  \n")
 						}
 					}
-					f.WriteString("#### Parameters\n")
+					f.WriteString("\n#### Parameters\n")
 					if len(dps.Params) == 0 {
 						f.WriteString("This function has no parameters.  \n")
 					}

cmd/docgen/docgen.lua

@@ -17,17 +17,53 @@ for _, fname in ipairs(files) do
 	pieces[mod] = {}
 
 	local docPiece = {}
+	local lines = {}
+	local lineno = 0
 	for line in f:lines() do
+		lineno = lineno + 1
+		lines[lineno] = line
+
 		if line == header then goto continue2 end
 		if not line:match(emmyPattern) then
 			if line:match '^function' then
 				local pattern = (string.format('^function %s%%.', mod) .. '(%w+)')
 				local funcName = line:match(pattern)
 				if not funcName then goto continue2 end
-				print(line)
+
-				print(pattern)
+				local dps = {
-				print(funcName)
+					description = {},
-				pieces[iface][funcName] = docPiece
+					params = {}
+				}
+
+				local offset = 1
+				while true do
+					local prev = lines[lineno - offset]
+
+					local docline = prev:match '^%-+ (.+)'
+					if docline then
+						local emmy = docline:match '@(%w+)'
+						local cut = 0
+
+						if emmy then cut = emmy:len() + 3 end
+						local emmythings = string.split(docline:sub(cut), ' ')
+
+						if emmy then
+							if emmy == 'param' then
+								table.insert(dps.params, 1, {
+									name = emmythings[1],
+									type = emmythings[2]
+								})
+							end
+						else
+							table.insert(dps.description, 1, docline)
+						end
+						offset = offset + 1
+					else
+						break
+					end
+				end
+
+				pieces[mod][funcName] = dps
 			end
 			docPiece = {}
 			goto continue2
@@ -39,20 +75,57 @@ for _, fname in ipairs(files) do
 	::continue::
 end
 
+local header = [[---
+title: %s %s
+description: %s
+layout: doc
+menu:
+  docs:
+    parent: "Nature"
+---
+
+]]
+
 for iface, dps in pairs(pieces) do
 	local mod = iface:match '(%w+)%.' or 'nature'
-	local path = string.format('luadocs/api/%s/%s.md', mod, iface)
+	local path = string.format('docs/%s/%s.md', mod, iface)
-	local f <close> = io.open(path, 'a+')
+	fs.mkdir(fs.dir(path), true)
+	local f <close> = io.open(path, 'w')
+	f:write(string.format(header, 'Module', iface, 'No description.'))
 	print(f)
 
 	print(mod, path)
-	fs.mkdir(fs.dir(path), true)
 
 	for func, docs in pairs(dps) do
+		f:write(string.format('<hr>\n<div id=\'%s\'>', func))
+		local sig = string.format('%s.%s(', iface, func)
+		for idx, param in ipairs(docs.params) do
+			sig = sig .. ((param.name:gsub('%?$', '')))
+			if idx ~= #docs.params then sig = sig .. ', ' end
+		end
+		sig = sig .. ')'
+		f:write(string.format([[			
+<h4 class='heading'>
+%s
+<a href="#%s" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+]], sig, func))
+
+		f:write(table.concat(docs.description, '\n') .. '\n')
+		f:write '#### Parameters\n'
+		if #docs.params == 0 then
+			f:write 'This function has no parameters.  \n'
+		end
+		for _, param in ipairs(docs.params) do
+			f:write(string.format('`%s` **`%s`**\n', param.name:gsub('%?$', ''), param.type))
+		end
+		--[[
 		local params = table.filter(docs, function(t)
 			return t:match '^%-%-%- @param'
 		end)
-		f:write(string.format('## %s(', func))
 		for i, str in ipairs(params) do
 			if i ~= 1 then
 				f:write ', '
@@ -66,7 +139,8 @@ for iface, dps in pairs(pieces) do
 				f:write(str:match '^%-%-%- (.+)' .. '\n')
 			end	
 		end
-		f:write('\n')
+		]]--
+		f:write('</div>')
+		f:write('\n\n')
 	end
-	f:flush()
 end

docs/api/bait.md

@@ -52,7 +52,6 @@ bait.catch(name, cb)
 
 Catches an event. This function can be used to act on events.  
 
-  
 #### Parameters
 `string` **`name`**  
 The name of the hook.
@@ -78,6 +77,7 @@ bait.catchOnce(name, cb)
 </h4>
 
 Catches an event, but only once. This will remove the hook immediately after it runs for the first time.  
+
 #### Parameters
 `string` **`name`**  
 The name of the event
@@ -97,6 +97,7 @@ bait.hooks(name) -> table
 </h4>
 
 Returns a list of callbacks that are hooked on an event with the corresponding `name`.  
+
 #### Parameters
 `string` **`name`**  
 The name of the function
@@ -116,7 +117,6 @@ Removes the `catcher` for the event with `name`.
 For this to work, `catcher` has to be the same function used to catch  
 an event, like one saved to a variable.  
 
-  
 #### Parameters
 `string` **`name`**  
 Name of the event the hook is on
@@ -147,7 +147,6 @@ bait.throw(name, ...args)
 
 Throws a hook with `name` with the provided `args`.  
 
-  
 #### Parameters
 `string` **`name`**  
 The name of the hook.

docs/api/commander.md

@@ -52,6 +52,7 @@ commander.deregister(name)
 </h4>
 
 Removes the named command. Note that this will only remove Commander-registered commands.  
+
 #### Parameters
 `string` **`name`**  
 Name of the command to remove.
@@ -70,7 +71,6 @@ commander.register(name, cb)
 Adds a new command with the given `name`. When Hilbish has to run a command with a name,  
 it will run the function providing the arguments and sinks.  
 
-  
 #### Parameters
 `string` **`name`**  
 Name of the command

docs/api/fs.md

@@ -42,6 +42,7 @@ fs.abs(path) -> string
 
 Returns an absolute version of the `path`.  
 This can be used to resolve short paths like `..` to `/home/user`.  
+
 #### Parameters
 `string` **`path`**  
 
@@ -59,6 +60,7 @@ fs.basename(path) -> string
 
 Returns the "basename," or the last part of the provided `path`. If path is empty,  
 `.` will be returned.  
+
 #### Parameters
 `string` **`path`**  
 Path to get the base name of.
@@ -75,6 +77,7 @@ fs.cd(dir)
 </h4>
 
 Changes Hilbish's directory to `dir`.  
+
 #### Parameters
 `string` **`dir`**  
 Path to change directory to.
@@ -92,6 +95,7 @@ fs.dir(path) -> string
 
 Returns the directory part of `path`. If a file path like  
 `~/Documents/doc.txt` then this function will return `~/Documents`.  
+
 #### Parameters
 `string` **`path`**  
 Path to get the directory for.
@@ -110,7 +114,6 @@ fs.glob(pattern) -> matches (table)
 Match all files based on the provided `pattern`.  
 For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match  
 
-  
 #### Parameters
 `string` **`pattern`**  
 Pattern to compare files with.
@@ -141,7 +144,6 @@ fs.join(...path) -> string
 
 Takes any list of paths and joins them based on the operating system's path separator.  
 
-  
 #### Parameters
 `string` **`path`** (This type is variadic. You can pass an infinite amount of parameters with this type.)  
 Paths to join together
@@ -165,10 +167,10 @@ fs.mkdir(name, recursive)
 
 Creates a new directory with the provided `name`.  
 With `recursive`, mkdir will create parent directories.  
-  
 -- This will create the directory foo, then create the directory bar in the  
 -- foo directory. If recursive is false in this case, it will fail.  
 fs.mkdir('./foo/bar', true)  
+
 #### Parameters
 `string` **`name`**  
 Name of the directory
@@ -192,6 +194,7 @@ fs.readdir(path) -> table[string]
 </h4>
 
 Returns a list of all files and directories in the provided path.  
+
 #### Parameters
 `string` **`dir`**  
 
@@ -214,7 +217,6 @@ size (number) - Size of the path in bytes
 mode (string) - Unix permission mode in an octal format string (with leading 0)  
 isDir (boolean) - If the path is a directory  
 
-  
 #### Parameters
 `string` **`path`**  
 

docs/api/hilbish/_index.md

@@ -57,7 +57,6 @@ hilbish.alias(cmd, orig)
 
 Sets an alias, with a name of `cmd` to another command.  
 
-  
 #### Parameters
 `string` **`cmd`**  
 Name of the alias
@@ -87,7 +86,6 @@ hilbish.appendPath(dir)
 
 Appends the provided dir to the command path (`$PATH`)  
 
-  
 #### Parameters
 `string|table` **`dir`**  
 Directory (or directories) to append to path
@@ -119,6 +117,7 @@ A `scope` is currently only expected to be `command.<cmd>`,
 replacing <cmd> with the name of the command (for example `command.git`).  
 The documentation for completions, under Features/Completions or `doc completions`  
 provides more details.  
+
 #### Parameters
 `string` **`scope`**  
 
@@ -138,6 +137,7 @@ hilbish.cwd() -> string
 </h4>
 
 Returns the current directory of the shell  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -153,6 +153,7 @@ hilbish.exec(cmd)
 
 Replaces the currently running Hilbish instance with the supplied command.  
 This can be used to do an in-place restart.  
+
 #### Parameters
 `string` **`cmd`**  
 
@@ -171,6 +172,7 @@ hilbish.goro(fn)
 Puts `fn` in a Goroutine.  
 This can be used to run any function in another thread.  
 **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**  
+
 #### Parameters
 `function` **`fn`**  
 
@@ -220,7 +222,6 @@ line and cursor position. It is expected to return a string which is used
 as the text for the hint. This is by default a shim. To set hints,  
 override this function with your custom handler.  
 
-  
 #### Parameters
 `string` **`line`**  
 
@@ -249,6 +250,7 @@ hilbish.inputMode(mode)
 Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.  
 `emacs` is the default. Setting it to `vim` changes behavior of input to be  
 Vim-like with modes and Vim keybinds.  
+
 #### Parameters
 `string` **`mode`**  
 
@@ -266,6 +268,7 @@ hilbish.interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/
 
 Runs the `cb` function every `time` milliseconds.  
 This creates a timer that starts immediately.  
+
 #### Parameters
 `function` **`cb`**  
 
@@ -287,7 +290,6 @@ hilbish.multiprompt(str)
 Changes the text prompt when Hilbish asks for more input.  
 This will show up when text is incomplete, like a missing quote  
 
-  
 #### Parameters
 `string` **`str`**  
 
@@ -322,6 +324,7 @@ hilbish.prependPath(dir)
 </h4>
 
 Prepends `dir` to $PATH.  
+
 #### Parameters
 `string` **`dir`**  
 
@@ -373,6 +376,7 @@ hilbish.read(prompt) -> input (string)
 Read input from the user, using Hilbish's line editor/input reader.  
 This is a separate instance from the one Hilbish actually uses.  
 Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).  
+
 #### Parameters
 `string` **`prompt?`**  
 
@@ -389,6 +393,7 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin
 </h4>
 
 Runs `cmd` in Hilbish's shell script interpreter.  
+
 #### Parameters
 `string` **`cmd`**  
 
@@ -412,6 +417,7 @@ Hilbish wll try to run input as Lua and/or sh or only do one of either.
 Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),  
 sh, and lua. It also accepts a function, to which if it is passed one  
 will call it to execute user input instead.  
+
 #### Parameters
 `string|function` **`mode`**  
 
@@ -429,6 +435,7 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
 
 Runs the `cb` function after `time` in milliseconds.  
 This creates a Timer that starts immediately.  
+
 #### Parameters
 `function` **`cb`**  
 
@@ -449,6 +456,7 @@ hilbish.which(name) -> string
 
 Checks if `name` is a valid command.  
 Will return the path of the binary, or a basename if it's a commander.  
+
 #### Parameters
 `string` **`name`**  
 

docs/api/hilbish/hilbish.aliases.md

@@ -28,6 +28,7 @@ hilbish.aliases.add(alias, cmd)
 </h4>
 
 This is an alias (ha) for the [hilbish.alias](../#alias) function.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -42,6 +43,7 @@ hilbish.aliases.delete(name)
 </h4>
 
 Removes an alias.  
+
 #### Parameters
 `string` **`name`**  
 
@@ -59,7 +61,6 @@ hilbish.aliases.list() -> table[string, string]
 
 Get a table of all aliases, with string keys as the alias and the value as the command.  
 
-  
 #### Parameters
 This function has no parameters.  
 #### Example
@@ -81,6 +82,7 @@ hilbish.aliases.resolve(alias) -> string?
 </h4>
 
 Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.  
+
 #### Parameters
 `string` **`alias`**  
 

docs/api/hilbish/hilbish.completion.md

@@ -30,7 +30,6 @@ hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string)
 Return binaries/executables based on the provided parameters.  
 This function is meant to be used as a helper in a command completion handler.  
 
-  
 #### Parameters
 `string` **`query`**  
 
@@ -73,6 +72,7 @@ hilbish.completion.call(name, query, ctx, fields) -> completionGroups (table), p
 Calls a completer function. This is mainly used to call a command completer, which will have a `name`  
 in the form of `command.name`, example: `command.git`.  
 You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.  
+
 #### Parameters
 `string` **`name`**  
 
@@ -99,6 +99,7 @@ hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string)
 
 Returns file matches based on the provided parameters.  
 This function is meant to be used as a helper in a command completion handler.  
+
 #### Parameters
 `string` **`query`**  
 
@@ -124,7 +125,6 @@ This function contains the general completion handler for Hilbish. This function
 completion of everything, which includes calling other command handlers, binaries, and files.  
 This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.  
 
-  
 #### Parameters
 `string` **`line`**  
 The current Hilbish command line

docs/api/hilbish/hilbish.editor.md

@@ -30,6 +30,7 @@ hilbish.editor.getLine() -> string
 </h4>
 
 Returns the current input line.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -44,6 +45,7 @@ hilbish.editor.getVimRegister(register) -> string
 </h4>
 
 Returns the text that is at the register.  
+
 #### Parameters
 `string` **`register`**  
 
@@ -60,6 +62,7 @@ hilbish.editor.insert(text)
 </h4>
 
 Inserts text into the Hilbish command line.  
+
 #### Parameters
 `string` **`text`**  
 
@@ -76,6 +79,7 @@ hilbish.editor.getChar() -> string
 </h4>
 
 Reads a keystroke from the user. This is in a format of something like Ctrl-L.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -90,6 +94,7 @@ hilbish.editor.setVimRegister(register, text)
 </h4>
 
 Sets the vim register at `register` to hold the passed text.  
+
 #### Parameters
 `string` **`text`**  
 

docs/api/hilbish/hilbish.history.md

@@ -31,6 +31,7 @@ hilbish.history.add(cmd)
 </h4>
 
 Adds a command to the history.  
+
 #### Parameters
 `string` **`cmd`**  
 
@@ -47,6 +48,7 @@ hilbish.history.all() -> table
 </h4>
 
 Retrieves all history as a table.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -61,6 +63,7 @@ hilbish.history.clear()
 </h4>
 
 Deletes all commands from the history.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -75,6 +78,7 @@ hilbish.history.get(index)
 </h4>
 
 Retrieves a command from the history based on the `index`.  
+
 #### Parameters
 `number` **`index`**  
 
@@ -91,6 +95,7 @@ hilbish.history.size() -> number
 </h4>
 
 Returns the amount of commands in the history.  
+
 #### Parameters
 This function has no parameters.  
 </div>

docs/api/hilbish/hilbish.jobs.md

@@ -35,7 +35,6 @@ hilbish.jobs.add(cmdstr, args, execPath)
 Creates a new job. This function does not run the job. This function is intended to be  
 used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.  
 
-  
 #### Parameters
 `string` **`cmdstr`**  
 String that a user would write for the job
@@ -62,6 +61,7 @@ hilbish.jobs.all() -> table[<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job
 </h4>
 
 Returns a table of all job objects.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -76,6 +76,7 @@ hilbish.jobs.disown(id)
 </h4>
 
 Disowns a job. This simply deletes it from the list of jobs without stopping it.  
+
 #### Parameters
 `number` **`id`**  
 
@@ -92,6 +93,7 @@ hilbish.jobs.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" st
 </h4>
 
 Get a job object via its ID.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -106,6 +108,7 @@ hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" sty
 </h4>
 
 Returns the last added job to the table.  
+
 #### Parameters
 This function has no parameters.  
 </div>

docs/api/hilbish/hilbish.module.md

@@ -64,6 +64,7 @@ hilbish.module.load(path)
 
 Loads a module at the designated `path`.  
 It will throw if any error occurs.  
+
 #### Parameters
 `string` **`path`**  
 

docs/api/hilbish/hilbish.runner.md

@@ -34,6 +34,7 @@ This is the same as the `hilbish.runnerMode` function.
 It takes a callback, which will be used to execute all interactive input.  
 In normal cases, neither callbacks should be overrided by the user,  
 as the higher level functions listed below this will handle it.  
+
 #### Parameters
 `function` **`cb`**  
 
@@ -51,6 +52,7 @@ hilbish.runner.lua(cmd)
 
 Evaluates `cmd` as Lua input. This is the same as using `dofile`  
 or `load`, but is appropriated for the runner interface.  
+
 #### Parameters
 `string` **`cmd`**  
 
@@ -68,6 +70,7 @@ hilbish.runner.sh(cmd)
 
 Runs a command in Hilbish's shell script interpreter.  
 This is the equivalent of using `source`.  
+
 #### Parameters
 `string` **`cmd`**  
 

docs/api/hilbish/hilbish.timers.md

@@ -48,6 +48,7 @@ hilbish.timers.create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbis
 </h4>
 
 Creates a timer that runs based on the specified `time`.  
+
 #### Parameters
 `number` **`type`**  
 What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
@@ -70,6 +71,7 @@ hilbish.timers.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#tim
 </h4>
 
 Retrieves a timer via its ID.  
+
 #### Parameters
 `number` **`id`**  
 

docs/api/terminal.md

@@ -28,6 +28,7 @@ terminal.restoreState()
 </h4>
 
 Restores the last saved state of the terminal  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -42,6 +43,7 @@ terminal.saveState()
 </h4>
 
 Saves the current state of the terminal.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -56,6 +58,7 @@ terminal.setRaw()
 </h4>
 
 Puts the terminal into raw mode.  
+
 #### Parameters
 This function has no parameters.  
 </div>
@@ -71,6 +74,7 @@ terminal.size()
 
 Gets the dimensions of the terminal. Returns a table with `width` and `height`  
 NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.  
+
 #### Parameters
 This function has no parameters.  
 </div>

docs/features/opts.md

@@ -0,0 +1,78 @@
+---
+title: Options
+description: Simple customizable options.
+layout: doc
+menu: 
+  docs:
+    parent: "Features"
+---
+
+Opts are simple toggle or value options a user can set in Hilbish.
+As toggles, there are things like `autocd` or history saving. As values,
+there is the `motd` which the user can either change to a custom string or disable.
+
+Opts are accessed from the `hilbish.opts` table. Here they can either
+be read or modified
+
+### `autocd`
+#### Value: `boolean`
+#### Default: `false`
+
+The autocd opt makes it so that lone directories attempted to be executed are
+instead set as the shell's directory.
+
+Example:
+```
+~/Directory                                     
+∆ ~
+~                                                                             
+∆ Downloads
+~/Downloads                                                                   
+∆ ../Documents
+~/Documents                                                                   
+∆ 
+```
+
+<hr>
+
+### `history`
+#### Value: `boolean`
+#### Default: `true`
+Sets whether command history will be saved or not.
+
+<hr>
+	
+### `greeting`
+#### Value: `boolean` or `string`
+The greeting is the message that Hilbish shows on startup
+(the one which says Welcome to Hilbish).
+
+This can be set to either true/false to enable/disable or a custom greeting string.
+
+<hr>
+
+### `motd`
+#### Value: `boolean`
+#### Default: `true`
+The message of the day shows the current major.minor version and
+includes a small range of things added in the current release.
+
+This can be set to `false` to disable the message.
+
+<hr>
+
+### `fuzzy`
+#### Value: `boolean`
+#### Default: `false`
+Toggles the functionality of fuzzy history searching, usable
+via the menu in Ctrl-R. Fuzzy searching is an approximate searching
+method, which means results that match *closest* will be shown instead
+of an exact match.
+
+<hr>
+
+### `notifyJobFinish`
+#### Value: `boolean`
+#### Default: `true`
+If this is enabled, when a background job is finished,
+a [notification](../notifications) will be sent.

docs/nature/dirs.md

@@ -0,0 +1,79 @@
+---
+title: Module dirs
+description: No description.
+layout: doc
+menu:
+  docs:
+    parent: "Nature"
+---
+
+<hr>
+<div id='setOld'>			
+<h4 class='heading'>
+dirs.setOld(d)
+<a href="#setOld" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sets the old directory string.
+#### Parameters
+`d` **`string`**
+</div>
+
+<hr>
+<div id='push'>			
+<h4 class='heading'>
+dirs.push()
+<a href="#push" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Add `d` to the recent directories list.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='peak'>			
+<h4 class='heading'>
+dirs.peak(num)
+<a href="#peak" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Look at `num` amount of recent directories, starting from the latest.
+#### Parameters
+`num` **`number`**
+</div>
+
+<hr>
+<div id='pop'>			
+<h4 class='heading'>
+dirs.pop(num)
+<a href="#pop" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Remove the specified amount of dirs from the recent directories list.
+#### Parameters
+`num` **`number`**
+</div>
+
+<hr>
+<div id='recent'>			
+<h4 class='heading'>
+dirs.recent(idx)
+<a href="#recent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Get entry from recent directories list based on index.
+#### Parameters
+`idx` **`number`**
+</div>
+

nature/commands/doc.lua

@@ -19,9 +19,11 @@ local function transformHTMLandMD(text)
 	:gsub('|(.-)|(.-)|', function(entry1, entry2)
 		return string.format('%s - %s', entry1, entry2)
 	end)
-	:gsub('^\n\n', '\n')
+	:gsub('<hr>', '{separator}')
+	:gsub('<.->', '')
+	--:gsub('^\n\n', '\n')
 	:gsub('\n%s+\n', '\n\n')
-	:gsub('  \n', '\n\n')
+	--:gsub('  \n', '\n\n')
 	:gsub('{{< (%w+) `(.-)` >}}', function(shortcode, text)
 		return docfuncs.renderInfoBlock(shortcode, text)
 	end)
@@ -34,8 +36,6 @@ local function transformHTMLandMD(text)
 	:gsub('`[^\n].-`', lunacolors.cyan)
 	:gsub('#+ (.-\n)', function(heading) return lunacolors.blue(lunacolors.bold('→ ' .. heading)) end)
 	:gsub('%*%*(.-)%*%*', lunacolors.bold)
-	:gsub('<hr>', '{separator}')
-	:gsub('<.->', '')
 end
 
 commander.register('doc', function(args, sinks)
@@ -64,6 +64,10 @@ Available sections: ]] .. table.concat(modules, ', ')
 		local valsStr = docs:match '^%-%-%-\n.-\n%-%-%-'
 		if valsStr then
 			docs = docs:sub(valsStr:len() + 2, #docs)
+			local pre = docs:sub(1, 1)
+			if pre == '\n' then
+				docs = docs:sub(2)
+			end
 
 			-- parse vals
 			local lines = string.split(valsStr, '\n')

nature/dirs.lua

@@ -40,7 +40,7 @@ function dirs.peak(num)
 	return dirRecents(num)
 end
 
---- Add `d` to the recent directories.
+--- Add `d` to the recent directories list.
 function dirs.push(d)
 	dirs.recentDirs[dirs.recentSize + 1] = nil
 	if dirs.recentDirs[#dirs.recentDirs - 1] ~= d then
@@ -51,19 +51,19 @@ function dirs.push(d)
 	end
 end
 
---- Remove `num` amount of dirs from the recent directories.
+--- Remove the specified amount of dirs from the recent directories list.
 -- @param num number
 function dirs.pop(num)
 	return dirRecents(num, true)
 end
 
---- Get entry from recent directories.
+--- Get entry from recent directories list based on index.
 -- @param idx number
 function dirs.recent(idx)
 	return dirs.recentDirs[idx]
 end
 
---- Sets the old directory.
+--- Sets the old directory string.
 -- @param d string
 function dirs.setOld(d)
 	ok, d = pcall(fs.abs, d)