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.
Basic commands and usage example. You can see the docs generated for the example here
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
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
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.
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:
- Install Docsify:
npm i docsify-cli -g
- And run:
docsify serve docs
Here is how the example collection will be visualized with Docsify
You can browse it here
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.
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.
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
}
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.
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>'
]
}
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
This is a list of examples of collections projects made with Collman. Feel free to submit a Pull Request adding yours too!
- Collman fruits example. A fruit collection.
- How to live. A collectin of life advices.
- Book Sentences. A collection of sentences from different books.