Metadata-Version: 2.4
Name: quick-notes
Version: 1.0.1
Summary: Markdown dialect with support to metadata and toml serialization
Author-email: Daniel Martins Antunes <danoan2008@gmail.com>
License: MIT License
        
        Copyright (c) 2022-present Daniel Martins Antunes <danoan2008@gmail.com>
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Documentation, https://github.com/danoan/quick-notes#readme
Project-URL: Issues, https://github.com/danoan/quick-notes/issues
Project-URL: Source, https://github.com/danoan/quick-notes
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: dataclasses
Requires-Dist: jinja2
Requires-Dist: typing_extensions
Requires-Dist: importlib_resources
Requires-Dist: lark
Requires-Dist: toml_dataclass
Dynamic: license-file

# Getting started with quick-notes

Markdown dialect with support to metadata and toml serialization. [Read the
docs](https://danoan.github.io/quick-notes).

## Features

- Markdown with metadata.
- Markdown <--> toml.
- CLI to generate and validate .md and .toml quick-notes.

## What is a quick-note?

A quick-note is a markdown document labeled with a set of metadata and that can
be exported to toml format.

## Why quick-note 

- Programmatically update of markdown documents.
- General purpose toml format.


### Markdown quick-note 

A markdown quick-note is a markdown text wrapped within special
markdown comments starting with `<!--BEGIN-->` and ending with
`<!--END-->`. 

Here is the `ingredients.md` file.

```
<!--BEGIN id=0 date="2022-12-30T09:07:33.934408" -->
# 2022-12-30T09:07
I should remember to buy:

- Apples
- Milk
- Sugar

<!--END-->
```

A markdown quick-note text always starts with a title. The `<!--BEGIN-->`
statement accepts any list of key-value attributes that could be represented as
a string or as an integer.

Any quick-note in the markdown document can be easily update or removed thanks
to the markdown quick-note parser.

### Toml quick-note

A markdown quick-note can be converted to the general purpose toml format. Therefore,
the markdown quick-notes data can be used in a different markup/render mechanism of 
choice. 

The `ingredients.md` above would have the corresponding `ingredients.toml`:

```toml
[[list_of_quick_note]]
id = 0
date = "2022-12-30T09:07:33.934408"
title = "2022-12-30T09:07"
text = "I should remember to buy\n\n- Apples\n- Milk\n - Sugar\n\n"
```

## CLI application

The CLI application supports the following commands:

- generate-toml: converts a markdown quick-note to toml quick-note.
- generate-markdown: converts a toml quick-note to markdown quick-note.
- validate: check if a toml quick-note and a markdown quick-note are equivalent.
- generate-quick-note: generate a toml quick-note according to a data-layout.

To create toml quick-notes you need to specify a data-layout.

### Data Layout 

A data layout is a python dataclass with support to write and read toml files. The `quick-notes` package comes with a single data layout named: `QuickNote`.

```python   
@dataclass
class QuickNote(QuickNoteBase):
    id: int
    date: str
```

One can extend the `QuickNote` class or create its own. The attributes specified in the data-layout will be automatically
rendered in both markdown and toml representations of the quick-note.

```{caution} 
Instantiate derived classes of QuickNoteBase using keyword arguments only. Otherwise, the attributes
could be assigned values different from those expected.
```

## API module   

The CLI application relies on the quick-notes api. One can import the module `api` to create new applications using quick-notes.

