Nocti

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Quickstart Guide#

This guide will help you install Nocti and get started with your first project.

Installation#

Download Binaries#

You can download the latest pre-compiled binaries for your system from the GitHub Releases page.

If using downloaded binaries on macOS, nocti may be blocked. Go to your Privacy and Security settings, and click the button to allow nocti to run.

Build from Source#

If you have Go (1.26.2+) installed, you can build Nocti manually:

Calendar

Mon, 01 Jan 0001 00:00:00 +0000

Calendar Resource#

The Calendar resource in Nocti provides a chronological timeline for managing events and notes tied to specific dates.

Overview#

Unlike notebooks, which are primarily hierarchical folder structures, calendars are centered around a specific creation date and provide a linear view of time.

Features#

Date-Based Listing#

Center Date: Calendars are automatically centered around their creation date.
Configurable Length: By default, a calendar shows 30 days before and 30 days after its creation date (61 days total). This can be customized during creation.
Chronological Order: Days are listed from earliest to latest, making it easy to see past and future contexts.
Year Grouping: If a calendar spans multiple years, dates are automatically organized into year-based “folders” (e.g., 2023/, 2024/).

Information Panel (Preview)#

When you select a day in the calendar, the preview pane displays a detailed information panel:

Todo Lists

Mon, 01 Jan 0001 00:00:00 +0000

Todo Lists#

Todo lists in Nocti allow you to manage tasks and track progress directly from the file list. A Todo resource is a specialized container that organizes markdown-based task lists and other sub-resources.

Creating a Todo Resource#

You can create a new Todo resource using the CLI:

nocti new todo --name "Project Tasks"

Or within the interactive list view by pressing n and selecting Todo.

Managing Tasks#

Within a Todo resource, you can create Todo Lists. These are standard Markdown files that utilize checkboxes for task tracking.

Templates

Mon, 01 Jan 0001 00:00:00 +0000

Templates#

Templates allow you to create new pages with pre-filled content and dynamic metadata. They are specific to each resource (notebook, todo, or calendar) and are stored within the resource itself.

Setup#

To use templates in a resource, create a hidden directory named .templates at the root of that resource.

cd my-notebook
mkdir .templates

Any markdown (.md) files you place in this folder will automatically appear as options in the “New” dialog within nocti list.

Mon, 01 Jan 0001 00:00:00 +0000

`nocti init`#

The init command initializes a new Nocti project in the current working directory.

Usage#

nocti init [flags]

Description#

Running nocti init creates a hidden .nocti/ directory containing a nocti.json file. This file serves as the central configuration and registry for all resources (notebooks, todo lists, calendars) created within the project.

You cannot run nocti init inside an existing Nocti resource directory.

Flags#

-p, --project string: The name of the Nocti project. If not provided, you will be prompted to enter one.

Examples#

Initialize a project with a specific name:

Mon, 01 Jan 0001 00:00:00 +0000

`nocti list`#

The list command displays the content of a notebook resource.

Usage#

nocti list [resource-name]

Description#

The list command recursively scans a directory and identifies all .md and .txt files. It is specifically designed to work with notebook resources.

Interactive Creation#

While in interactive mode, you can press n to create new files, folders, or sub-resources. If you have defined templates for the current resource, they will also appear in this menu. See the Templates page for more details.

Mon, 01 Jan 0001 00:00:00 +0000

`nocti new`#

The new command creates a new resource (notebook, todo list, or calendar) within a Nocti project.

Usage#

nocti new [command] [flags]

Description#

Resources are the primary way to organize information in Nocti. Each resource is created as a directory containing a hidden .nocti.json file with its metadata (ID, name, type, and parent information).

Hierarchical Resources#

If you run nocti new while inside another resource’s directory, the new resource will be created as a child of the current one. This relationship is tracked in:

Mon, 01 Jan 0001 00:00:00 +0000

Notebook Customization#

You can customize the appearance of the nocti list command by defining colors in your main .nocti/nocti.json file.

Color Configuration#

Add an optional colors key at the top level of your nocti.json file:

{
 "name": "my-project",
 "version": "development",
 "colors": {
 "file_list_bg": "blue",
 "file_list_fg": "white",
 "preview_pane_bg": "orange",
 "preview_pane_fg": "white"
 },
 ...
}

Supported Colors#

The following color names are supported (assuming your terminal has 256-color support):


`black`	`red`	`green`	`yellow`
`blue`	`magenta`	`cyan`	`white`
`gray`	`darkgray`	`lightgray`	`silver`
`brightred`	`brightgreen`	`brightyellow`	`brightblue`
`brightmagenta`	`brightcyan`	`brightwhite`	`orange`
`darkorange`	`pink`	`hotpink`	`purple`
`violet`	`brown`	`navy`	`teal`
`olive`	`maroon`	`aqua`	`fuchsia`
`lime`	`skyblue`	`gold`	`indigo`
`coral`	`turquoise`	`plum`	`orchid`
`salmon`

Default Colors#

If no colors are defined, the following defaults are used:

Mon, 01 Jan 0001 00:00:00 +0000

`nocti update`#

The update command synchronizes the central .nocti/nocti.json registry with the actual resource directories present in the project.

Usage#

nocti update

Description#

Running nocti update scans the immediate subdirectories of the project root for hidden .nocti.json files. For every resource found, it reads the metadata and rebuilds the resource lists (notebooks, todos, calendars) in the main configuration file.

This is useful if:

Resources were manually moved or deleted.
The main nocti.json file became corrupted or out of sync.
You are importing an existing set of resource folders into a new Nocti project.

Constraints#

Project Root Only: This command must be run from the project root directory (where the .nocti/ folder resides). It will fail if run inside an individual resource directory.
Immediate Children: Only directories directly inside the project root are scanned. Nested sub-resources are currently updated via their parent’s metadata but are registered in the main config when created.

Examples#

Rebuild the project registry:

Nocti

Quickstart

Quickstart Guide#

Installation#

Download Binaries#

Build from Source#

Calendar

Calendar Resource#

Overview#

Features#

Date-Based Listing#

Information Panel (Preview)#

Todo Lists

Todo Lists#

Creating a Todo Resource#

Managing Tasks#

Templates

Templates#

Setup#

nocti init#

Usage#

Description#

Flags#

Examples#

nocti list#

Usage#

Description#

Interactive Creation#

nocti new#

Usage#

Description#

Hierarchical Resources#

Notebook Customization#

Color Configuration#

Supported Colors#

Default Colors#

nocti update#

Usage#

Description#

Constraints#

Examples#

`nocti init`#

`nocti list`#

`nocti new`#

`nocti update`#