DOCSEARCHbyAlgolia
Submit Docs

tasks.md

repository·main·Indexed 24 days ago

https://github.com/baldissaramatheus/tasks.md

A self-hosted, Markdown-based task management board that provides a modern web interface for managing tasks stored as local files. It allows for easy synchronization with other Markdown-based tools like Obsidian, using a filesystem-based structure where directories represent lanes and Markdown files represent tasks.

Tokens
4.2K
Snippets
9
Records
28
Agent score
80%

What's inside tasks.md

  1. Understand the Tasks.md file structure

    main

    Tasks.md uses your filesystem as the source of truth. The mapping is direct:

    • Lanes are directories in your filesystem.
    • Tasks are Markdown files within those directories.

    Example Structure: If you have lanes named Backlog, Sprint, and Done, and a task named Something something in the Done lane, your filesystem should look like:

    • /tasks/Backlog/ (directory)
    • /tasks/Sprint/ (directory)
    • /tasks/Done/Something something.md (file)

    Sub-projects: You can treat sub-directories as independent projects by opening the app under that specific subpath.

  2. Breaking changes in Tasks.md 3.0.X

    main

    The transition from version 2.X.X to 3.0.X introduced the following breaking changes:

    • CSS: Import paths and custom properties (variables) have been replaced.
    • Images: Local image paths changed from host/api/images to host/_api/image.
    • Tags: The syntax for tags changed from tags: a, b, c to [tag:a].

  3. Install Tasks.md from Source

    main

    To run the project from source:

    1. Clone the repository: git clone --recursive.
    2. Open a terminal in the /frontend directory and run npm install then npm start.
    3. Open a second terminal in the /backend directory and run npm install then npm start.

    Environment Variables: Variables are defined in the package.json files for both directories. In addition to the Docker variables, you must set:

    • CONFIG_DIR: Path to the configuration directory.
    • TASKS_DIR: Path to the tasks directory.

  6. Install dependencies for the frontend template

    main

    The project uses pnpm to maintain template dependencies (via pnpm up -Lri), which results in a pnpm-lock.yaml file. However, you can use any package manager to install dependencies. If you prefer not to use pnpm, you can safely remove the pnpm-lock.yaml file after cloning the template.

    $ npm install # or pnpm install or yarn install

  7. Navigate the Tasks.md board

    main

    Use Vim-style keys or arrow keys to move focus between cards and lanes. You can also use Alt modifiers to reorder cards or move them between lanes.

    | Key        | Action                                                        |
| ---------- | ------------------------------------------------------------- |
| `↑` or `k` | Move focus to the card above (vim-style)                      |
| `↓` or `j` | Move focus to the card below (vim-style)                      |
| `←` or `h` | Move focus to the first card in the previous lane (vim-style) |
| `→` or `l` | Move focus to the first card in the next lane (vim-style)     |
| `Alt+↑`    | Move the focused card up within its current lane              |
| `Alt+↓`    | Move the focused card down within its current lane            |
| `Alt+←`    | Move the focused card to the previous lane                    |
| `Alt+→`    | Move the focused card to the next lane                        |

  9. Customize Tasks.md appearance with CSS

    main

    You can customize the UI by creating or editing a custom.css file located in the /config directory (if using Docker).

    To change the overall theme, you can replace the default adwaita theme with nord or catppuccin. For deep customization, use frontend/src/stylesheets/index.css as a reference.

  10. Upgrade Tasks.md from 2.X.X to 3.X.X

    main

    To upgrade to version 3.X.X, follow these steps to handle breaking changes in CSS, image paths, and tag syntax:

    1. Stop Containers: Stop all running Tasks.md containers.
    2. Backup Custom Styles: (Optional) Backup any custom files in color-themes or changes made to custom.css.
    3. Reset Stylesheets: Delete the /config/stylesheets directory. This directory will be recreated automatically when the new container starts.
    4. Deploy New Container: Start a new container using the latest Docker image.
    5. Restore Custom Styles: (Optional) Move your backed-up color-themes back and re-apply changes to custom.css. Note: The color-theme import path has changed; check the top of the file to ensure the path is correct.
    6. Update Image Paths: (Optional) In your files, replace local image paths from {host}/api/images/{fileName} to {host}/_api/image/{fileName}.
    7. Update Tag Syntax: (Optional) In your files, replace the old tag syntax tags: tag one, tag two, etc with the new syntax [tag:tag one] [tag:two]. Tags can be placed anywhere in the file and order does not matter.
    8. Update CSS Variables: (Optional) If using custom styles, note that some CSS custom properties (vars) have been replaced. Refer to the project README for the updated list of variables.

  11. Install Tasks.md via docker-compose

    main

    Use the following docker-compose.yml configuration to deploy Tasks.md. You can customize environment variables and volumes using the same logic as the Docker CLI command.

    version: "3"
services:
  tasks.md:
    image: baldissaramatheus/tasks.md
    container_name: tasks.md
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - /path/to/tasks:/tasks
      - /path/to/config:/config
    restart: unless-stopped
    ports:
      - 8080:8080

  12. Build the application for production

    main
    Use npm run build to create a production-ready build. This command bundles Solid in production mode and optimizes the build for performance. The output is placed in the dist folder. The build is minified, and filenames include hashes for cache busting.
    npm run build