Giter Site home page Giter Site logo

reymon359 / collman Goto Github PK

View Code? Open in Web Editor NEW
3.0 2.0 0.0 2 MB

Easily manage and display agnostic collections

Home Page: https://reymon359.github.io/collman

License: MIT License

JavaScript 2.76% TypeScript 91.20% HTML 5.53% Shell 0.51%
collection collections manager cli agnostic markdown docsify typescript

collman's Introduction

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!

collman's People

Contributors

reymon359 avatar

Stargazers

 avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

collman's Issues

Refactor: Improve the typing

Right now I am adding a lot of ts-ignores and any to develop faster but I have to have a look at this in the future.

  • Check jdown for typing
  • Remove all any
  • Remove all ts-ignores

Use cases diagram

Create a use case diagram and add it to the project. Preferably in UML

Custom configuration

Have a custom config in the directory which values overwrite the default ones

  • add logic to load the custom one
    - [ ] add tests that if there is custom loads the custom
    - [ ] mock the config loader and pass a custom config and check that loads it instead the default

Moving last ones to #39

Feature: add quantity to classifications

Classifications Version 1

export interface Classification {
  name: string
  values: [string]
}

Classifications Version 2

export interface ClassificationValue {
  name: string
  quantity: number
}

export interface Classification {
  name: string
  values: [ClassificationValue]
}

Feature: use a collman.config

  • Use some kind of collman.config file like with the docsify config for the overall config
  • If does not exists load the default

Set up milestones

Set up the milestones of this project.

ADD DATES to them and add them to the notebook too to be aware of them

Refactor: update save collection

Some things are missing for saving the collection

  • Add an index.md to the classifications
  • Urlify the links to the classification values
  • Update relative paths
  • Update output mocks

Create entities

Think about the entities and types needed

  • Create the collection entities
  • Create classification entities

Load config

  • create a default config
  • load the default config

Fix this collection controller get collection test

Fix this test
Right now is throwing this error

Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout.Error
: Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout.
Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout.Error: 
    at new Spec (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/Spec.js:116:22)
    at new Spec (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/setup_jest_globals.js:78:9)
    at new JBPatchedSpec (/Applications/WebStorm.app/Contents/plugins/JavaScriptLanguage/helpers/jest-intellij/lib/jest-intellij-jasmine-reporter.js:94:7)
    at specFactory (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/Env.js:523:24)
    at Env.it (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/Env.js:592:24)
    at Env.it (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmineAsyncInstall.js:134:23)
    at it (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/jasmineLight.js:100:21)
    at Suite.<anonymous> (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/src/infrastructure/controllers/collection.test.ts:7:3)
    at addSpecsToSuite (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/Env.js:444:51)
    at Env.describe (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/Env.js:414:11)
    at describe (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/jasmine/jasmineLight.js:88:18)
    at Object.<anonymous> (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/src/infrastructure/controllers/collection.test.ts:6:1)
    at Runtime._execModule (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-runtime/build/index.js:1299:24)
    at Runtime._loadModule (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-runtime/build/index.js:898:12)
    at Runtime.requireModule (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-runtime/build/index.js:746:10)
    at jasmine2 (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-jasmine2/build/index.js:230:13)
    at runTestInternal (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-runner/build/runTest.js:380:22)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
    at runTest (/Users/ramonmorcillo/Documents/developer/graphql-nextjs/node_modules/jest-runner/build/runTest.js:472:34)

Refactor: update save collection tests

The repository markdown save collection tests are not working properly. Fix and update them

Also add

  • add tests that if there is custom loads the custom
  • mock the config loader and pass a custom config and check that loads it instead the default

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.