zord-tree/README.md

# zord-tree

[![Build Status](https://drone.arns.lt/api/badges/zordsdavini/zord-tree/status.svg)](https://drone.arns.lt/zordsdavini/zord-tree)

Library for golang to build articles tree from file system. The file should be in specific format to hold meta data, id and
content. For now it supports markdown format.

Process should go in two steps:

* populate existing `source` directory with formatting files, add missing `id` and meta data
* separate images and other data files to ex. `__a` root directory
* build `Tree` to operate on object for your app
* read file content without meta data by path


## File and tree format

### Category

During building `Tree` directory path is converted into array of categories. So, file in path `linux/command/video` will get
categories: `linux`, `command`, `video`.

### Split line

File meta should be split by `---` line. If there is markdown formating to mark header, first such case (`---`) will be formatted
to contain empty line. Example:

```
Text
---
```

will become

```
Text

---
```

### Meta data

Meta data separated by lines and in format `* name: value`. By default library supports `tags` as comma separated array.
During populating tree it adds missing `id` in `abcex` format and empty meta data lines and saves in `source` directory.

Additionally it moves images and other not `.md` files to separate `__a` root directory and replace in content linked urls.

There is possibility to add custom default value. That is passed with custom function what returns string.

### File structure

```
* tags: linux,command,video
* meta1: example
* meta2: some long description

---

Hear goes content. It can be written in html, markdown or whatever what can be processed later
```


## Usage

There are two main commands: `PopulateTree` to prepare source (format, add metadata and add Id) and separate images and other data files and `BuildTree` to get object of tree.

Also both commands use `Config` object that can be prepared by `NewConfig` command. With it can be configurable readable formats, attachment directory, custom meta, excludes (not movable files by regexp) and list of functions to apply before file formatting (read bellow).

`Tree` object has methods: `FileById` to get `File` by Id, `Slice` to get sub-tree of given path and `Filter` to filter tree by filter.
Filter contains array of meta key and searching value. `tag` key is searched as equal and other meta values of keys can contain part. If `-` is before key - filter is filter out.

By full file path and config meta there is possibility to get file params: `Id`, `Meta` and `Tags`:

```
GetFileParams(fullPath string, meta []string) (string, []string, map[string]string, error)
```

### Functions to apply before file formatting

There is possibility to add custom functions to apply before file formatting. That is passed with custom function what returns string.

```
func(dir string, content string, info os.FileInfo) (string, error)
```

`dir` is path to directory of file, `content` is file content and `info` is file info.