buuk/README.md

<p align="center"><img src="http://groundedrob.com/images/projects/buk.png" height='250px'></p>

## About Bük
> Markdown based Javascript wiki engine.

Bük is a flat file markdown based wiki engine written in Javascript.  

**No server needed.**

Simply drop in your .md files in a folder, update manifest.json and you get a blazing fast wiki with an integrated fuzzy search feature.

## Get started

1) Get Bük ( via npm or git clone)
> ##### NPM
NPM is the recommended way of installing Bük.

```
npm install buuk
```

> ##### Git Clone
Alternatively, you can install Bük by directly cloning the repository from Github

```
git clone https://github.com/hang-up/buk.git buk
npm install
```
---

2) Drop your markdown files inside `dist/assets`.
3) Update `manifest.json`
4) `npm run build`


## Usage
# Manifest.json

The heart of Bük is laying on its `manifest.json` file. The manifest for the current boilerplate follows this structure:
```
    {
        "app": "Name of the wiki",
        "version": "1.0.0",
        "description": "General description of the wiki.",
        "sub": "More details about the wiki.",
        
        "options": {
            "advanced_slugs: true
        }

        "articles" : {                              // All articles to be indexed
            "Category 1": [                         // Category name
              {
                "title": "Article title",           // Article name
                "tags": [                           // Tags to use when searched
                  "tag 1",
                  "tag 2",
                  "tag 3"
                ]
              }
            ]
        }
    }
```

### File naming convention
**Your markdown (.md) file names must match the slug generated by Bük or defined in `manifest.json`.**
See the options section below to know more about how we auto generate slugs.

### Options
#### advanced_slugs
1. When `advanced_slugs` is set to `true` (default setting), Bük will generate a slug based on the following pattern: `direct-parent-category-title-of-the-article` (eg. usage-manifest.json).
2. When set to `false`, Bük will simply take the title of the article as slugs (eg. manifest.json)

> Advanced slugs are useful when having multiple articles with the same title defined in the manifest.

#### Override slugs
By default, Bük will generate a slug for every article indexed in the manifest.json file based on its `title` key.  
If you wish to have a custom slug for an article, simply add a `"slug"` key to your article.
```
{
    "title": "Article title",   // Article name
    "tags": [                   // Tags to use when searched
        "tag 1",
        "tag 2",
        "tag 3"
    ],
    "slug": "custom-slug"       // Associated .md file must be named custom-slug.md
}
```

### Nested categories
Bük allows an infinite degree of nested categories. Simply build your hierarchy inside `manifest.json` and name your markdown files accordingly. 
An example of manifest using nested categories:
```
"articles" : {
    "Level 0": {
        "Level 1" : {
            "Level 2 Category 1": [
                {
                    "title": "Article Title",   // level-2-category-1-article-title.md
                    "tags": [
                        "licence",
                        "author",
                        "misc"
                    ]
                }
            ],
            
            "Level 2 Category 2": [
                {
                    "title": "Article Title",   // level-2-category-2-article-title.md
                    "tags": [
                        "licence",
                        "author",
                        "misc"
                    ]
                }
            ]
        }
    }
}
```

### Built using:
* [vue](https://vuejs.org/) -  [vuex](https://vuex.vuejs.org) - [vue-router](https://router.vuejs.org)
* [fuse.js](http:http://fusejs.io/)

### Parser
Bük is using [markdown-it](https://github.com/markdown-it/markdown-it) as a parser to display your markdown pages. If you encounter any parsing caveats, please address your issues [here](https://github.com/markdown-it/markdown-it/issues).  

### Licence
MIT