Skip to content

Latest commit

 

History

History
291 lines (216 loc) · 11 KB

README.md

File metadata and controls

291 lines (216 loc) · 11 KB
Raw

collman

Collman

CI Last commit License: MIT Version

Easily manage and display agnostic collections.

We, as humans tend to classify things, to group them, is in our nature. This project aims to create a tool to help managing any collection and classify its content in an agnostic way.

Create anything with just Markdown to edit the content effortlessly.

Table of Contents

How to use it

Basic commands and usage example. You can see the docs generated for the example here

Install Collman

Running npm i -g collman will do

If you are using a npm version 5.2.0 or above you can just run npx collman

Create a collection

Let's create a fruits' collection as an example. You can find it in the assets/examples directory from this repository.

First, create a directory with any name you want.

📁 fruits-collection

Now create a directory for your items and add an index.md file to it. In this example the fruits.

📁 fruits-collection
└── 📁 fruits
    └── 📄 index.md

Inside the ìndex.md file add a name for your collection in the front matter and a description about your collection outside it.

---
name: 'Fruits Collection'
---
# This is my awesome collection of fruits

Now lets add an item to the items directory. An item is nothing but a directory that contains at least an index.md file with the content of your item.

📁 fruits-collection
└── 📁 fruits
    └── 📁 apple
    │   └── 📄 index.md
    └── 📄 index.md

Add the name inside the index.md front matter and the content below it.

---
name: 'Apple'
---
Apples are **amazing.**

Additionally, an item can contain an assets directory to store images referenced in the index.md. Have a look at the watermelon item in our example.

📁 fruits-collection
└── 📁 fruits
    └── 📁 apple
    │   └── 📄 index.md
    └── 📁 orange
    │   └── 📄 index.md
    └── 📁 watermelon
    │   └── 📁 assets
    │   │   └── 📄 watermelon.png
    │   └── 📄 index.md
    ├── ...
    ...
    └── 📄 index.md

This would be its index.md.

---
name: 'Watermelon'
---
I like this watermelon picture
 
![watermelon](./assets/watermelon.png)

And finally you can add Classifications to your items. A Classification is an agnostic way to group items according to the values you give to it. You just have to add an array of values in the front matter of the item. Here I am adding two classifications to my orange item index.md: Color and Size and adding them some values.

---
name: 'Orange'
Color: ['Orange']
Size: ['Medium']
---
It is my favourite fruit

Run collman

Once we have the collection ready, in a terminal in the collection directory, we run collman --id name-input-directory (or npx collman --id name-input-directory if you are using at least npm version 5.2.0). Going on with the previous example it would be collman --id fruits. The input directory name is not needed if you name your directory ìtems which is the default one. As we named it fruits we have to pass the command line argument.

You will see this output:

user@user-pc fruits-collection % collman --id fruits
👀 Getting collection based on the configuration
✅ Collection got: Fruits Collection
🚧 Processing collection and saving in directory: docs
🎉 Collection processed and saved successfully
🎨 Docsify enabled. Adding it to the collection
🖼 Docsify added successfully to the collection. To have a look just do two things:
1. Install Docsify: npm i docsify-cli -g
2. Run: docsify serve docs

This will create a docs directory with the collection ready. Go to https://github.com/reymon359/collman/tree/master/assets/examples/fruits-collection/docs to see the one auto generated for the example. Here is a sandbox with it.

Visualize it

By default, the collection generated is made to be easily visualized on a markdown viewer or GitHub. Have a look at the example collection fruits-collection docs.

To visualize a Collection in a better way, Collman generates the files needed to integrate with Docsify.. Therefore, you just have to:

  1. Install Docsify: npm i docsify-cli -g
  2. And run: docsify serve docs

Here is how the example collection will be visualized with Docsify

Example fruits collection

You can browse it here

Why Docsify

At first Collman was supposed to include something similar to display a collection. Then decided to not reinvent the wheel and research documentation libraries to fulfil this purpose.

I found Docsify to be the simplest one of them to work with markdown files. The minimum requirement is just to add an index.html to the directory you want to serve.

It also has plenty of official and community-made plugins to improve the way you display the content which added key features for Collman.

Configuration

Some behavior of Collman can be configured to get a different output.

Value Type Description Default value Command line argument
pathRootDirectory string The path of the directory containing the items' directory './' (The current path) --prd
inputDirectory string The directory name with the collection items 'items' --id
outputDirectory string The directory name for the output collection 'docs' --od
docsify boolean Enable Docsify visualization with the collection true --ds

There are to ways of working with the Collman configuration.

Configuration file

You can add a configuration file named collman.config.js in the root directory with the config you want. If you don't add a value it will use the default one.

Example

module.exports = {
  pathRootDirectory: './',
  inputDirectory: 'fruits',
  outputDirectory: 'docs',
  docsify: true
}

Command line arguments

You can also pass all the configuration values as command line arguments. We did it with the input directory in the fruits' collection example collman --id fruits.

Check the configuration table above to see how to use them.

Docsify config file

You can configure the Docsify visualiitacion in a way similar to collman.config.js.

First create a docsify.config.js file like the one below:

module.exports = {
  main: {
  },
  scriptsAndLinks:[]
}

It has two parts: The main and the scriptsAndLinks.

The first one makes reference to the attributes that you pass to the window docsify object window.$docsify = {}. The second one is an array with the scripts and links we want to load.

Here is an example with the default Collman values:

module.exports = {
  main: {
    name: 'Default Collection',
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    },
    subMaxLevel: 3,
    sidebarDisplayLevel: 1,
    search: 'auto'
  },
  scriptsAndLinks:[
    '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">',
    '<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>',
    '<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>',
    '<script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>',
    '<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar.min.css" />',
    '<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/js/docsify-themeable.min.js"></script>',
    '<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>',
    '<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>'
  ]
}

Deploy

You can deploy a Collman project by serving the output directory on your own or using platforms like Netlify or GitHub Pages.

Just select the branch and directory where you have the docs (or the name you gave to the output directory).

For GitHub Pages you will need to add a basePath to the docsify config. Therefore you will need to create a docsify.config.js file with it. Have a look at this example repository https://github.com/reymon359/collman-fruits-example

Examples

This is a list of examples of collections projects made with Collman. Feel free to submit a Pull Request adding yours too!