diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..485dee6 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea diff --git a/README.md b/README.md index 87774e6..a377ce5 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,207 @@ # noted -Powerful CLI for taking markdown notes in a journal-like (time-seried) fashion + +_Lightweight CLI for taking markdown notes in a journal-like (time-seried) fashion on macOS._ + +## Contents + +- [Features](#features) +- [Getting Started](#getting-started) + * [Required steps](#required-steps) + * [Optional steps](#optional-steps) +- [Typical usage](#typical-usage) +- [Subcommand reference](#subcommand-reference) +- [Configuration guide](#configuration-guide) + * [Default values](#default-values) + * [Configuring custom values](#configuring-custom-values) + * [Custom template file](#custom-template-file) +- [Recommended aliases](#recommended-aliases) + +## Features + +_Noted_ can do the following and more: + +- Automatically create a markdown file for you, named with today's date (in a customizable date format) +- Append note entries from the command line automatically, formatted with a Markdown template you can customize +- Timestamp all entries with a customizable timestamp format +- Quickly open the notes from any given date for you to view or edit +- Work with any text editor, with no interference between `noted` and the editor + +## Getting Started + +### Required steps + +Getting started with _Noted_ only requires that `noted` is placed on your path. + +A good standard way to do this is to symlink the `noted` script to `/usr/local/bin` as follows. + +1. Open a terminal. +2. Change to your `Documents` directory. + +```shell +cd $HOME/Documents +``` + +3. Clone this repository to your Documents folder. + +```shell +git clone git@github.com:scottashipp/noted.git -C $HOME/Documents +``` + +4. Symlink the file: + +```shell +ln -s $HOME/Documents/noted/noted /usr/local/bin/noted +``` + +6. Verify that it is visible on the path: + +```shell +noted version +``` + +If the above outputs `noted v0.0.1` then all is well. Check out the [Typical usage](#typical-usage) section below to take your first notes! + +### Optional steps + +You may want to follow the [configuration guide](#configuration-guide) if you do not like the defaults. + +## Typical usage + +You're a developer. It's 8am and you start work on a new project. From your terminal, you type: + +```shell +noted 'Begin creating Foo' +``` + +A new Markdown file is automatically created with today's date in your configured directory. + +> Note: The default directory is $HOME/Documents/noted. It will be created for you if it doesn't exist. + +Second, `noted` also creates the following _automatic entry:_ + +```markdown +--- +8:00:44 UTC + +# Begin creating Foo + +--- +``` + +At 9am, you have a meeting with the Foo team. You type `noted` in your terminal to start a new note. Your default editor opens to today's file, the template is +automatically appended to the end, and it is timestamped for you. You use this entry to take notes during your meeting, which include links, images, and code. + +Later, you start work again, and note this: + +```shell +noted 'Working on foo again.' +``` + +You're trying to remember what your team talked about in last week's meeting, so you view the notes for that day: + +```shell +noted view 2021-09-27 +``` + +This opens the file from that date with your default editor. + +After a bit, you open a pull request for Foo. You type: + +```shell +noted +``` + +This automatically opens today's file in your default editor, and appends a new entry using the template. In the resulting new entry, you record the link to the +PR. + +The rest of the day goes similarly. At the end of the day, you check in your notes to Git. + +Your notes page, when viewed as HTML looks [just like this](example-notes-page.md): + +![](example-notes-page.jpeg) + +You now have a source-controlled, time-seried journal of events. Most importantly, these notes look great and include links, snippets of code, and images. + +## Subcommand reference + +_Noted_ works like many other CLI's, through the use of subcommands. It currently supports config, create, edit, version, and view. These are fully-specified in +the [subcommand reference](subcommands.md) + +## Configuration guide + +### Default values + +The following default values are configured. + +| Property | Description | Default Value | +| :-- | :-- | :-- | +| NOTED_MARKDOWN_HOME | The place where markdown files are automatically generated. | `$HOME/Documents/noted` | +| NOTED_FILE_NAME_DATE_FORMAT | The date format string used as the file name for new notes. | `"+%Y-%m-%d"` | +| NOTED_TIMESTAMP_FORMAT | The timestamp format for the timestamp placed on new entries. | `"+%H:%M:%S UTC"` | +| NOTED_TEMPLATE_FILE | A file containing a Markdown-formatted entry template to use. | `""`
(It is empty by default. Which means the script's own default template will be used.) | + +### Configuring custom values + +To configure custom values, you may place a `.notedconfig` file in your `$HOME` directory. + +For example, saving the following contents into `$HOME/.notedconfig` will alter the behavior of `noted` accordingly: + +```text +# Save my notes here instead +NOTED_MARKDOWN_HOME=$HOME/Documents/mynotes +# Use month-date-year instead of year-month-date as the file names +NOTED_FILE_NAME_DATE_FORMAT="+%m-%d-%Y" +# Use Pacific time +NOTED_TIMESTAMP_FORMAT="+%H:%M:%S Pacific" +# Use my own template file +NOTED_TEMPLATE_FILE=$HOME/Documents/mynotes/template.md +``` + +Both the `NOTED_FILE_NAME_DATE_FORMAT` and the `NOTED_TIMESTAMP_FORMAT` are format strings as specified by the `date` shell command. You can learn more about +this format by reading the man page for `date`. + +### Custom template file + +_Noted_ templates only support the variables `TIMESTAMP` and `HEADERTEXT`. + +`TIMESTAMP` is replaced with the output of `date` as formatted by `NOTED_TIMESTAMP_FORMAT`. + +'HEADERTEXT' is the value of any argument passed to `noted` when quick-creating a note. Place it in your template so that this value is output. + +By default, `noted` uses the following template: + +```markdown +--- +TIMESTAMP + +# HEADERTEXT + +--- +``` + +Another valid custom template might be: + +```markdown +# HEADERTEXT + +_TIMESTAMP_ + + +``` + +## Recommended aliases + +Besides supplying a custom configuration, you probably want to add the following aliases to make using `noted` even easier: + +| Alias | Description | +| :-- | :-- | +| n | Alias for `noted` itself. | +| ne | Alias for `noted edit`. | +| nv | Alias for `noted version`. | +| nc | Alias for `noted config`. | + +## Usage with a static site generator + +Some people may prefer to use `noted` with a static site generator like [mkdocs](https://www.mkdocs.org) +, [Maven site](https://maven.apache.org/plugins/maven-site-plugin/), or [Hugo](https://gohugo.io/). Those are just a few examples. Doing so will allow you to +view your notes in HTML format locally. \ No newline at end of file diff --git a/example-notes-page.jpeg b/example-notes-page.jpeg new file mode 100644 index 0000000..cab4f86 Binary files /dev/null and b/example-notes-page.jpeg differ diff --git a/example-notes-page.md b/example-notes-page.md new file mode 100644 index 0000000..9d7a9eb --- /dev/null +++ b/example-notes-page.md @@ -0,0 +1,43 @@ +--- +7:45:44 UTC + +# This is the example notes page + +It comes from the [Typical Usage](README.md#typical-usage) section of the README. + +--- + +--- +8:00:44 UTC + +# Begin creating Foo + + +--- + +--- +9:00:44 UTC + +# Meet with the Foo team + +Whiteboarded over our virtual meeting. We came out with some great ideas! Check it out: + +![](nice-diagram.png) + +Also Dom showed us a really nice trick with Java: + +```java +System.out.println("Hello, World!" +``` + +--- + +--- +11:22:44 UTC + +# Foo's first pull request! + +🎉 We opened [Foo's first pull request today](https://github.com/scottashipp/noted/pulls/1)! + +--- + diff --git a/nice-diagram.png b/nice-diagram.png new file mode 100644 index 0000000..4d87d1a Binary files /dev/null and b/nice-diagram.png differ diff --git a/noted b/noted new file mode 100755 index 0000000..7d9a9bf --- /dev/null +++ b/noted @@ -0,0 +1,159 @@ +#!/bin/bash + +set -e + +# +# START FUNCTIONS (alphabetical order) +# + +checkForEnvVariable() { + varval=${!1} + if [ ! "$(echo $varval)" ]; then + cat <>"${markdownFile}" + else + # otherwise open it up with the template and let them edit + newEntry >>"${markdownFile}" + edit "${markdownFile}" + fi +} + +edit() { + open "${markdownFile}" +} + +loadProperties() { + if [[ -f "${CONFIG_FILE}" ]]; then + source "${CONFIG_FILE}" + fi +} + +markdownFile() { + markdownFile="${NOTED_MARKDOWN_HOME}/${1}.md" +} + +outputConfig() { + echo "The following configuration is currently being used:" + echo "NOTED_MARKDOWN_HOME=${NOTED_MARKDOWN_HOME}" + echo "NOTED_FILE_NAME_DATE_FORMAT=${NOTED_FILE_NAME_DATE_FORMAT}" + echo "NOTED_TIMESTAMP_FORMAT=${NOTED_TIMESTAMP_FORMAT}" + echo "NOTED_TEMPLATE_FILE=${NOTED_TEMPLATE_FILE:-<>}" +} + +validate() { + if [ -z "$1" ]; then + echo "${2}" + exit 1 + fi +} + +version() { + echo "noted v${VERSION}" +} + +view() { + open "${htmlFile}" +} + +# +# END FUNCTIONS +# + +VERSION="0.0.1" + +# +# Default Settings +# +# Settings that cannot be overridden +# Location of config file +CONFIG_FILE=$HOME/.notedconfig + +# Settings that can be overridden from properties +# name files like this +NOTED_FILE_NAME_DATE_FORMAT="+%Y-%m-%d" +# timestamp entries within the files like this +NOTED_TIMESTAMP_FORMAT="+%H:%M:%S UTC" +NOTED_TEMPLATE_FILE="" +# keep the directory where notes are stored here +NOTED_MARKDOWN_HOME=$HOME/Documents/notes + +# +# Override with any additional settings +# +loadProperties + +currDate=$(date "${NOTED_FILE_NAME_DATE_FORMAT}") +timestamp=$(date "${NOTED_TIMESTAMP_FORMAT}") + +todaysFile="${NOTED_MARKDOWN_HOME}/${currDate}.md" + +subcommand="$1" +if [[ "${subcommand}" == "config" ]]; then + outputConfig +elif [[ "${subcommand}" == "version" ]]; then + version +elif [[ "${subcommand}" == "edit" ]] || [[ "${subcommand}" == "view" ]]; then + arg="$2" + if [[ -z "${arg}" ]]; then + arg="${currDate}" + fi + markdownFile "${arg}" + edit "${markdownFile}" +else + # create / default + OPTIONAL_FILE="" + OPTIONAL_NOTE="" + if [[ "${subcommand}" == "create" ]]; then + shift + fi + if [[ -n "$1" ]]; then + OPTIONAL_NOTE="$1" + fi + if [[ -n "$2" ]]; then + OPTIONAL_FILE="$2" + fi + create "${OPTIONAL_NOTE}" "${OPTIONAL_FILE}" +fi diff --git a/subcommands.md b/subcommands.md new file mode 100644 index 0000000..b97d146 --- /dev/null +++ b/subcommands.md @@ -0,0 +1,186 @@ +# Subcommand reference + +All uses of `noted` require a subcommand. If one is not supplied, the default `create` subcommand is assumed. The subcommands are as follows. + +## Contents + +* [List of Subcommands](#list-of-subcommands) + + [config](#config) + - [Synopsis](#synopsis) + - [Overview](#overview) + - [Arguments & Flags](#arguments---flags) + - [Examples](#examples) + + [create](#create) + - [Synopsis](#synopsis-1) + - [Overview](#overview-1) + - [Arguments & Flags](#arguments---flags-1) + - [Examples](#examples-1) + + [edit / view](#edit---view) + - [Synopsis](#synopsis-2) + - [Overview](#overview-2) + - [Arguments & Flags](#arguments---flags-2) + - [Examples](#examples-2) + + [version](#version) + - [Synopsis](#synopsis-3) + - [Overview](#overview-3) + - [Arguments & Flags](#arguments---flags-3) + - [Examples](#examples-3) + +## List of Subcommands + +### config + +Lists the current configuration for _noted_. This is the combination of default values plus whatever is found in `$HOME/.notedconfig`, where values +in `$HOME/.notedconfig` take precedence. + +#### Synopsis + +```shell +noted config +``` + +#### Overview + +The config subcommand will: + +- Generate a quick view of the resulting configuration after applying the values in `$HOME/.notedconfig` + +#### Arguments & Flags + +N/A + +#### Examples + +View configuration: + +```shell +noted config +``` + +### create + +Create a new note. + +#### Synopsis + +```shell +noted create [Quoted text to use (optional)] [ALTERNATE_FILE_NAME (optional)] +``` + +#### Overview + +The create subcommand will: + +- Look for a file named with today's date, and create it if it doesn't exist +- Append the note template to the file named with today's date, with the current timestamp +- Open the file named with today's date +- Position the cursor in the entry title field + +> **Important:** +> +> We encourage users to omit `create` and use the alternate shorthand `noted` without the create keyword. The remainder +> of this documentation will use the shorthand. + +#### Arguments & Flags + +Both arguments are optional. When quoted text is included the text will automatically be appended to the entry and editing of the entry will be skipped. When +the `ALTERNATE_FILE_NAME` argument is supplied with a filename, then instead of using the automatic file (named with today's date), the file supplied will be +used. + +#### Examples + +Start a new entry: + +```shell +noted +``` + +Add a new note with the text "This is a quick note" as the title and an empty body: + +```shell +noted "This is a quick note" +``` + +Start a new entry in the file named `process.md`: + +```shell +noted 'Some note' process.md +``` + +### edit / view + +Open a specific note file, or today's file if no file is specified, in the default editor. + +#### Synopsis + +```shell +noted edit [FILE (optional)] +``` + +```shell +noted view [FILE (optional)] +``` + +#### Overview + +Edit and view are interchangeable. + +The edit / view subcommand will: + +- Look for the file passed as an argument +- If no file is passed, then it will assume today's file +- Open the given file in the default editor + +> NOTE: +> Edit is different than create. Create will also populate a new note entry into the given file using the template. +> Edit, on the other hand, will merely open the file. + +#### Arguments & Flags + +The `FILE` argument is optional. You should not include the extension. The Markdown extension `.md` is assumed. + +#### Examples + +Open today's file in the default editor. + +```shell +noted edit +``` + +Open the file from 2021-10-01: + +```shell +noted edit 2021-10-01 +``` + +Open a file named `process.md`: + +```shell +noted view process +``` + +### version + +View the current version of `noted`. + +#### Synopsis + +```shell +noted version +``` + +#### Overview + +The version subcommand will print out the current version of `noted`. + +#### Arguments & Flags + +N/A + +#### Examples + +View the version: + +```shell +noted version +```