Merge branch 'zk-org:main' into main

.github/workflows/build-docs.yml

@@ -0,0 +1,26 @@
+# Build the Sphinx docs on PR to catch any issues before merging.
+# Deployment happens on push to main with gh-pages.yml
+name: Build Docs
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  pages:
+    runs-on: ubuntu-20.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - id: deployment
+      uses: sphinx-notes/pages@v3
+      with:
+        publish: false

Makefile

@@ -68,7 +68,7 @@ clean:
 ### Sphinx Docs ###
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-docs: Makefile
+zkdocs: Makefile
 	mkdir -p docs-build
 	sphinx-build -a docs docs-build 
 

README.md

@@ -8,38 +8,35 @@
 
 `zk` is a command-line tool helping you to maintain a plain text [Zettelkasten](https://zettelkasten.de/introduction/) or [personal wiki](https://en.wikipedia.org/wiki/Personal_wiki).
 
-Looking for a quick usage example? [Let's get started](docs/getting-started.md).
+Looking for a [quick usage example?](https://zk-org.github.io/zk/tips/getting-started.html)
 
 Or want to see it in action? Checkout [Shivan's](https://github.com/shivan-s)
 video, [_Note-taking System ALL Programmers Should Consider_](https://www.youtube.com/watch?v=UzhZb7e4l4Y).
 
-
-
 ### Highlights
 
-* [Creating notes from templates](docs/note-creation.md)
-* [Advanced search and filtering capabilities](docs/note-filtering.md) including [tags](docs/tags.md), links and mentions
-* [Integration with your favorite editors](docs/editors-integration.md):
-    * [Any LSP-compatible editor](docs/editors-integration.md)
+* [Creating notes from templates](https://zk-org.github.io/zk/notes/note-creation.html)
+* [Advanced search and filtering capabilities](https://zk-org.github.io/zk/notes/note-filtering.html) including [tags](https://zk-org.github.io/zk/notes/tags.html), links and mentions
+* [Integration with your favorite editors](https://zk-org.github.io/zk/tips/editors-integration.html):
+    * [Any LSP-compatible editor](https://zk-org.github.io/zk/tips/editors-integration.html)
     * [`zk-nvim`](https://github.com/zk-org/zk-nvim) for Neovim 0.8+
     * [`zk-vscode`](https://github.com/zk-org/zk-vscode) for Visual Studio Code
-    * (*unmaintained*) [`zk.nvim`](https://github.com/megalithic/zk.nvim) for Neovim 0.5+ by [Seth Messer](https://github.com/megalithic)
-* [Interactive browser](docs/tool-fzf.md), powered by `fzf`
-* [Git-style command aliases](docs/config-alias.md) and [named filters](docs/config-filter.md)
-* [Made with automation in mind](docs/automation.md)
-* [Notebook housekeeping](docs/notebook-housekeeping.md)
-* [Future-proof, thanks to Markdown](docs/future-proof.md)
+* [Interactive browser](https://zk-org.github.io/zk/config/tool-fzf.html), powered by `fzf`
+* [Git-style command aliases](https://zk-org.github.io/zk/config/config-alias.html) and [named filters](https://zk-org.github.io/zk/config/config-filter.html)
+* [Made with automation in mind](https://zk-org.github.io/zk/tips/automation.html)
+* [Notebook housekeeping](https://zk-org.github.io/zk/tips/notebook-housekeeping.html)
+* [Future-proof, thanks to Markdown](https://zk-org.github.io/zk/tips/future-proof.html)
 * Supports most Markdown syntax flavors
     * Links: regular Markdown links, `[[Wikilinks]]` and Neuron's `[[Folgezettel links]]#`.
     * Tags: `#hashtags`, `:colon:separated:tags:`, Bear's `#multi-word tags#`.
-    * [YAML frontmatter](docs/note-frontmatter.md)
+    * [YAML frontmatter](https://zk-org.github.io/zk/notes/note-frontmatter.html)
 
 [See the changelog](CHANGELOG.md) for the list of upcoming features waiting to be released.
 
 ### What `zk` is not
 
 * A note editor.
-* A tool to serve your notes on the web – for this, you may be interested in [Neuron](docs/neuron.md) or [Gollum](https://github.com/gollum/gollum).
+* A tool to serve your notes on the web – for this, you may be interested in [Neuron](docs/tips/neuron.md) or [Gollum](https://github.com/gollum/gollum).
 
 ## Install
 

docs/conf.py

@@ -26,5 +26,5 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 master_doc = "index"

docs/index.rst

@@ -5,10 +5,6 @@
 .. image:: assets/media/screencast.svg
    :align: center
 
-`zk` is a plain text note-taking tool that leverages the power of the command line. 
-
-Let's :doc:`get started <tips/getting-started>`.
-
 .. toctree::
    :hidden:
    :titlesonly:
@@ -20,4 +16,63 @@ Let's :doc:`get started <tips/getting-started>`.
    notes/index
    tips/index
 
+`zk` is a plain text note-taking tool that leverages the power of the command line. 
+
+Install as below and then... :doc:`get zettling <tips/getting-started>`!
+
+Installation
+============
+
+Homebrew:
+
+.. code-block:: sh
+   
+   brew install zk
+
+   # Or, if you want to be on the bleeding edge:
+   brew install --HEAD zk
+
+
+Nix:
+
+.. code-block:: sh
+
+   # Run zk from Nix store without installing it:
+   nix run nixpkgs#zk
+
+   # Or, to install it permanently:
+   nix-env -iA zk
+
+Alpine Linux:
+
+.. code-block:: sh
+
+   # `zk` is currently available in the `testing` repositories:
+   apk add zk
+
+Arch Linux:
+
+You can install `the zk package <https://archlinux.org/packages/extra/x86_64/zk/>`_ from the official repos.
+
+.. code-block:: sh
+
+   sudo pacman -S zk
+
+Build from scratch:
+
+Make sure you have a working `Go 1.21+ installation <https://golang.org/>`_, then clone the repository:
+
+.. code-block:: sh
+
+   git clone https://github.com/zk-org/zk.git
+   cd zk
+
+On macOS / Linux:
+
+.. code-block:: sh
+
+   make
+   ./zk -h
+
+