Markdown rewrite using hugo

.github/workflows/actions.yaml

@@ -15,8 +15,8 @@ jobs:
         run: |
           python3 -m venv /tmp/venv
           /tmp/venv/bin/pip install --upgrade pip
-          /tmp/venv/bin/pip install -r tools/requirements.txt
-          /tmp/venv/bin/python tools/update.py html/tools/tools-data.json
+          /tmp/venv/bin/pip install -r bin/requirements.txt
+          /tmp/venv/bin/python bin/update.py static/tools-data.json
       - name: Create Pull Request
         id: cpr
         uses: peter-evans/create-pull-request@v3

.gitignore

@@ -1,2 +1,3 @@
 venv/
 update_tools.sh
+.hugo_build.lock

README.md

@@ -2,21 +2,38 @@
 
 This repository contains the content of the taskwarrior.org site.
 
+## Contributing
 
-## To Clone this Repository:
+To clone this repository, run
 ```sh
 git clone https://github.com/GothenburgBitFactory/tw.org.git
 ```
 
+For minor changes, it is perfectly fine to simply change the relevant Markdown files and make a pull request.
 
-## Instruction For Updating tw.org/html/tools
+For more complex changes, here is how to build the documentation locally:
+
+1. Install [hugo](https://gohugo.io/getting-started/quick-start/).
+2. Run
+   ```sh
+   hugo server -D -w
+   ```
+   This defaults to running a web server on `http://localhost:1313`.  
+   If you are running on an external host, try 
+   ```sh
+   hugo server -D -w --bind 0.0.0.0 -b http://<hostname>
+   ```
+
+## Updating Tools
+
+This repository has automation for searching GitHub for projects related to TaskWarrior and including them in the "Tools" page.
 
 On first usage, generate API tokens and store them safely for later:
 
 * [GitHub](https://github.com/settings/tokens): requires no special scopes
 
 
-Then setup the Python 3 environment:
+Then set up the Python 3 environment:
 
 ```sh
 # Create a virtual environment to avoid clobbering global installation
@@ -33,7 +50,7 @@ $ pip install -r tools/requirements.txt
 Then create the `update_tools.sh` script by copying the sample, and set API keys there. This file will be ignored and should not be committed.
 
 
-Now that everything is setup, the tools can be updated by running `update_tools.sh`:
+Now that everything is set up, the tools can be updated by running `update_tools.sh`:
 
 ```sh
 $ source venv/bin/activate

archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+lang: en
+---
+

config.toml

@@ -0,0 +1,13 @@
+baseURL = "https://taskwarrior.org"
+languageCode = "en-us"
+title = "Taskwarrior"
+theme = "bootstrap"
+publishDir = "html"
+
+[params]
+description = "Taskwarrior is Free and Open Source Software that manages your TODO list from the command line."
+
+[markup]
+    [markup.tableOfContents]
+        endLevel = 2
+        ordered = false

content/about.md

@@ -0,0 +1,7 @@
+---
+title: "Taskwarrior - About"
+---
+
+![Infrastructure provided by Göteborg Bit Factory.](/images/gbf.png)
+
+Göteborg Bit Factory is the organization that pays the bills, and supports all our Open Source projects.

content/backup

@@ -0,0 +1,54 @@
+### Rule Actions
+
+When a rules matches, an action is taken. There are currently four supported
+actions:
+
+-   `line`
+-   `match`
+-   `blank`
+-   `suppress`
+
+#### The `line` Action
+
+The `line` action instructs Clog to color the entire line. This makes the whole
+line more visible. An example might be to color a line in a log file if that
+line reports a critical error.
+
+#### The `match` Action
+
+The `match` action instructs clog to only color the matching pattern and not the
+entire line. This make individual keywords more visible. An example might be to
+highlight simply an error code, or server name.
+
+#### The `blank` Action
+
+The `blank` action causes a blank line to be written both before and after the
+matching line. This is another form of emphasis.
+
+#### The `suppress` Action
+
+The `suppress` action causes the whole line to be removed from the output. You
+will not see a suppressed line at all. This is useful for stripping out noise
+from a log file.
+
+#### Example
+
+Here is a default rule set that includes all the different actions. The first
+rule will make any line completely blue if it contains the word \'blue\'. The
+second rule colors the word \'red\' red. The third puts blank lines around any
+line containing the word \'emphasize\'. The fourth rule suppresses any line
+containing the word \'ignore\'.
+
+![](/docs/clog/images/action1.png){.img-responsive}
+
+Here is a sample file that triggers every rule, so we shoud see the actions of
+all rules taken. Can you predict what will happen?
+
+![](/docs/clog/images/action2.png){.img-responsive}
+
+Here is the output:
+
+![](/docs/clog/images/action3.png){.img-responsive}
+
+This shows rules precedence also - the second rule finds the word \'red\' in the
+blue line.

content/conduct.md

@@ -0,0 +1,13 @@
+---
+title: "Taskwarrior - Code of Conduct"
+---
+
+### Taskwarrior Code of Conduct
+
+We are here to improve the software.
+There is no agenda.
+
+Be respectful of all contributors, all contributions, and everyone\'s time, in all project-related forums.
+No exceptions.
+
+To report violations, please contact [[email protected]](mailto:[email protected]), and we will do the right thing.

content/docs/30second.md

@@ -0,0 +1,72 @@
+---
+title: "Taskwarrior - 30-Second Tutorial"
+---
+
+# 30-Second Tutorial
+
+Let's get started.
+Here's a quick demonstration showing how to perform basic task management.
+
+Here is an explanation of what is happening.
+First add two tasks.
+
+```
+$ task add Read Taskwarrior documents later
+Created task 1.
+
+$ task add priority:H Pay bills
+Created task 2.
+```
+
+Easy.
+Do you see that second one has a High priority? Now look at those tasks, using the report `next`.
+Notice that the two tasks are ordered by urgency, and the urgency is affected by the priority, among other things.
+
+```
+$ task next
+
+ID Age P Description                      Urg
+-- --- - -------------------------------- ----
+ 2 10s H Pay bills                           6
+ 1 20s   Read Taskwarrior documents later    0
+```
+
+Suppose the bills are paid, and we wish to mark task 2 as completed.
+
+```
+$ task 2 done
+Completed task 2 'Pay bills'.
+Completed 1 task.
+```
+
+Now we can omit the `next` command, because it is the default command.
+
+```
+$ task
+
+ID Age Description                      Urg
+-- --- -------------------------------- ----
+ 1 5m  Read Taskwarrior documents later    0
+```
+
+Task 2 is now gone.
+Notice that no visible tasks have a priority set, and so the priority column is not shown.
+Now we can delete that remaining task, because we are already using the tutorial.
+
+```
+$ task 1 delete
+Permanently delete task 1 'Read Taskwarrior documents later'? (yes/no) y
+Deleting task 1 'Read Taskwarrior documents later'.
+Deleted 1 task.
+
+$ task
+No matches.
+```
+
+That is all you *need* to know.
+These four commands (add, done, delete, next) will allow you to use Taskwarrior effectively.
+If you are new to Taskwarrior, it is recommended that you stop here, go and start to manage your task list for a while.
+We don't want you to be overwhelmed at a time when you just need a way to organize and get things done.
+
+When you are comfortable with basic Taskwarrior usage, there are many other features you can learn about.
+While you are not expected to learn all of them, or even find them useful, you might just find exactly what you need.

content/docs/3rd-party.md

@@ -0,0 +1,52 @@
+---
+title: "Taskwarrior - 3rd-Party Application Guidelines"
+---
+
+# 3rd-Party Application Guidelines
+
+Taskwarrior can be extended by means of a third-party application, which can be a wrapper, or hook script.
+There are script examples of import and export add-ons that support many formats (clone the repository, look in `taskwarrior.git/scripts/add-ons`).
+Then there are more sophisticated applications such as [Vit](https://gothenburgbitfactory.org/projects/vit) that provide a complete replacement UI.
+
+All of these provide interesting new features and improve ease of use for different kinds of users.
+We encourage you to create such add-ons, but in doing so, there are some rules that must be followed, which will not only protect the user's data from mistreatment, but also your application from being sensitive to changes in Taskwarrior.
+
+## Rules
+
+- Produce, consume and handle UTF8 text properly.
+  UTF8 is the only text encoding supported by Taskwarrior.
+- Don\'t attempt to parse the pending.data file.
+  Here\'s why: the `.data` file format is currently on its fourth version.
+  The very first version was never released, so if you want to read Taskwarrior data properly, you will need to parse the three supported formats.
+  Those formats are not documented.
+  Additionally, you will need to handle the GC operations, implement the task \"unwait\" feature, observe user defined attribute handling restrictions, and implement recurring task synthesis all of which require `.taskrc` and default value access.
+  You would essentially be rewriting the data access and configuration portion of Taskwarrior, which is a major undertaking.
+  To support filters you would also need to evaluate the supported clauses, provide DOM access and implement aliases.
+  Then there is also the fifth data format, which is planned...
+- Use the `export` command to query data from Taskwarrior.
+  The `export` command implements filters which you can use, or you can omit a filter, get all the data, and implement your own filtering.
+  JSON parsing is very well-supported in all relevant programming languages, which means you should be using Taskwarrior itself to query the data, with a commodity JSON parser in conjunction.
+  While the JSON format will be tweaked over time, the general form will not.
+- Beginning with version {{< label >}}2.4.5{{< /label >}}, use the `import` command to import modified JSON back into Taskwarrior.
+- Older versions: Use the command line interface to put data into Taskwarrior.
+  Composing a valid command line is a simple way to put data in to Taskwarrior.
+- Use the `_get` helper command to access individual data items.
+  Note that multiple items can be retrieved by one command.
+  If accessing more than just a few items, use the `export` command.
+- Verify feature support by running `task --version`
+  This command returns the version number, which will help you determine whether a particular feature is supported or not.
+  Note that this command does not scan for a configuration file, and is therefore safe to run if Taskwarrior is not yet set up.
+- UDAs (User Defined Attributes) must be preserved in the data.
+  When reading the JSON for a task, there may be attributes that you have never encountered before.
+  If this is the case, you must not modify them in any way.
+  This not only makes your application future-proof, but allows it to tolerate UDAs from other data sources.
+  It also prevents the Taskserver from stripping out *your* data.
+
+## Guidelines
+
+- If you need to store additional data, consider putting your own data file in the `~/.task` directory.
+  Just don\'t use the file names `pending.data`, `completed.data`, `backlog.data`, or `undo.data`.
+- There are many helper commands designed to assist add-on scripts such as shell completion scripts.
+  These commands all begin with an underscore, see them with this command: `task help | grep ' _'`.
+- Familiarize yourself with the means of forcing color on or off, disabling word wrapping, disabling bulk operation limitations, disabling confirmation, disabling gc, modifying verbosity and so on.
+  There are ways around almost all the restrictions, and while these don\'t make sense for regular users, they can be critical for add-on authors.

content/docs/_index.md

@@ -0,0 +1,84 @@
+---
+lang: en
+title: 'Taskwarrior - Documentation'
+viewport: 'width=device-width, initial-scale=1'
+layout: single
+---
+
+{{< lead >}}Here is the complete set of Taskwarrior and Taskserver documentation.{{< /lead >}}
+
+## Getting Started
+
+- [Getting Started](/docs/start) - What to do first
+- [Introduction](/docs/introduction) - Welcome to Taskwarrior
+- [Configuration](/docs/configuration) - Creating a `.taskrc` file
+- [30-Second Tutorial](/docs/30second) - all you need to begin using Taskwarrior
+- [Getting Help](/docs/help)
+
+## Basic Usage
+
+- [Command Line Syntax](/docs/syntax)
+- [Best Practices](/docs/best-practices)
+- [Example Commands](/docs/examples) - Common uses of Taskwarrior
+- [Example Workflows](/docs/workflow) - Everyone uses Taskwarrior differently
+- [All the Commands](/docs/commands)
+- [Using Dates Effectively](/docs/using_dates)
+- [Unicode](/docs/unicode) {{< label >}}2.5.0{{< /label >}}
+- [Searching](/docs/searching)
+- [Reports](/docs/report)
+- [Filters](/docs/filter)
+- [Priority](/docs/priority) {{< label >}}2.4.3{{< /label >}}
+- [Tags & Virtual Tags](/docs/tags)
+- [Date & Time](/docs/dates) {{< label >}}2.4.0{{< /label >}}
+- [Named Dates](/docs/named_dates) {{< label >}}2.4.0{{< /label >}}
+- [Duration Values](/docs/durations) {{< label >}}2.4.0{{< /label >}}
+
+## Configuring Taskwarrior
+
+- [Configuration](/docs/configuration)
+- [Verbosity](/docs/verbosity)
+- [Color Themes](/docs/themes)
+- [Terminology](/docs/terminology) - a glossary of terms
+
+## Advanced Topics
+
+- [Urgency](/docs/urgency)
+- [ID Numbers](/docs/ids)
+- [Context](/docs/context) {{< label >}}2.4.2{{< /label >}}
+- [How Recurrence Works](/docs/recurrence)
+- [User Defined Attributes (UDAs)](/docs/udas)
+- [External Scripts](/tools)
+- [Escaping Command Line Characters](/docs/escapes)
+- [DOM - Document Object Model](/docs/dom)
+- [JSON Import/Export Format](https://github.com/GothenburgBitFactory/taskwarrior/blob/develop/docs/rfcs/task.md)
+- [Deprecated Features](/docs/deprecated)
+- [Philosophy](/docs/philosophy)
+
+## Taskserver
+- [Why do I need a Taskserver?](/docs/taskserver/why)
+- [Taskserver Setup Guide](https://gothenburgbitfactory.github.io/taskserver-setup)
+- [Taskserver Troubleshooting Guide](https://gothenburgbitfactory.github.io/taskserver-troubleshooting)
+
+## Tasksh
+- [Reviewing tasks using tasksh](/docs/review) {{< label >}}1.1.0{{< /label >}}
+
+## Other Projects
+- [Timewarrior Home Page](https://timewarrior.net)
+- [Clog Home Page](/docs/clog)
+
+## Integrating with Taskwarrior
+- [Hooks API](/docs/hooks) {{< label >}}2.4.0{{< /label >}}
+- [Hooks v2 API](/docs/hooks2) {{< label >}}2.4.3{{< /label >}}
+- [Hook Author\'s Guide](/docs/hooks_guide) {{< label >}}2.4.0{{< /label >}}
+- [3rd Party Application Guidelines](/docs/3rd-party)
+- [Design Documents (RFCs)](https://github.com/GothenburgBitFactory/taskwarrior/tree/develop/docs/rfcs)
+
+## Feedback
+- [How to Report a Bug](/docs/bugs)
+- [How to Request a Feature](/docs/features)
+- [How to ask a question](http://www.catb.org/esr/faqs/smart-questions)
+
+## About
+- [Taskwarrior Release History](/docs/history)
+- [Taskserver Release History](/docs/history_td)
+- [MIT License](/docs/license)