When coding, it is for me mandatory to write files with a limited number of lines and functions as well as 1 file >= 1 functionality.
The question now is why would I not impose the same rigor when writing a text / documentation about some subject.
Normally to do such thing, I use a rich text editor (such as Microsoft Word), write a summary, with a lot of sub-subjects in it. When doing that at some point there are subjects difficult to categorize to put in your section x page 10 or you section y page 30, that is the moment when I realize splitting the document might be interesting. Another use case that might appear is when you have repeated category of subject with the same sub-section, and sub-sub-sections... splitting it in multiple files is more interesting.
In case I want to write something bigger, with more people working on it, I will probably choose to use a CMS. This will allow me to write different types of content with some of the most used features of a Rich Text Edition thanks to WYSIWYG. This gives the possibility to a very details roles permissions to handle all kind of contributors on your project.
The downside of it, is when you want new types of content, you will need developers to release your new type of content even if no specific features are needed aside adding some fields with no dependency between contents. When you chose a CMS, you will have to think about your database, the charge your website can handle, if you need cache on your webpage... and so on.
Vemsy is a static website with the possibility to add features to it. Because it is a static website, no database are needed, the content is written in markdown files.
For those needs, Markdown solves most of them specially if you customize the css a little or use some that was done by others. Ex: markdown-css-themes
The list of all the features currently available:
- Render markdown files following folder structure
- Task loading setup
- Use of standard express middlewares to customize your app
- Add your own express middlewares
- Theme
- Route based feature / customization (Page, Template)
A boilerplate has been made with a cli vemsy-cli.
You can use it like that:
npm install -g vemsy-cli
vemsy new <my-project-name>
cd <my-project-name>
node app/index.js
The entry point is defined in your ./my-project-name/app/index.js defined all the tasks' loaders that will be executed to set up the application.
The cli installs the example folder
The technical documentation is filled in the setup folder: ./my-project-name/app/contents/ or ./my-project-name/app/contents/ If you execute the example the documentation is available through a vemsy server on http://localhost:1337