I noticed for myself that I constantly write down all sorts of trivia, useful information, just something from the clipboard right in a text editor. Always somewhere on the background hangs an open Sublime Text with a bunch of tabs.
And I also noticed that it is most convenient for me to structure the information in one file using the Markdown syntax - the source text is more pleasant, and not the result displayed on the same githabe.
Over time, I noticed that a lot of such saved files have accumulated, and the unclosed tabs are not going to decrease. But one careless movement and all not stored accumulated information will sink into oblivion, and you will not look at it from other devices, and it is also not very convenient to scatter on daddies.
All this led me to the idea of writing something like my own engine for storing all the information in one place and in a convenient form. Yes, yes, there are a lot of Evernote, some notes embedded in MacOS / iOS and so on, which are synchronized and have useful features - but, as they say, you want to do something well (for yourself), do it myself. And, like almost any programmer, in any incomprehensible situation, I take and write everything myself. So it happened this time.
What for?
Similar projects already exist, and the above mentioned monster services are also quite convenient, but some of its features in my project offer some advantages.
First of all, it is most convenient to use it as documentation for the project (actually, the inspiration came from the Kotlin documentation site, from which I borrowed most of the styles for the generated content).
The project is completely free and is in the public domain, a reference to the githab at the end of the article.
What can?
- Generate HTML on the fly - the result is not saved. Already finished articles can be copied in entire folders to the desired project directory. All added and removed files are automatically indexed.
- Navigation is also generated, not hardcoded.
- Search by content.
- Access control works approximately like “groups” of organizations on a githaba: each group (I called their role ) has a list of users and a list of paths to folders / files that users of this group can watch.
- When searching, navigating, etc. the user will not see those pages to which he has no access.
- Articles can also be added to the visual editor (it has syntax highlighting, buttons like on github, preview, etc.)
- Everything is easily configured through the settings page, which is also generated (and you can easily add new items). So, for a couple of commands, you can install a project locally, drop off ready-made Markdown files to your daddy, quickly set up access and use.
- A bunch of other small chips, like anchor links to all headers, buttons to copy over snippets with code, etc. etc.
How does it work?
On what?
I used NodeJS and express , since for me this stack seemed to be the least resource-time-consuming for the implementation of this particular task.
Access rights
The logic is quite simple - passport solves all problems with authorization. The rights for users and articles are stored in MongoDB , and the paths to the articles correspond to the paths to the files on the disk.
The “groups” themselves are not stored anywhere, the management happens “from below”: each user and the path (up to an article or category — that is, to a file and folder) have their own list of “roles”. If the user has at least one “role” from the list of the path he chooses, then he is considered to have access. To view any path, the user must have access to the path itself and to all parents: for example, to see the page /pages/Documentation/Habr , you must have access to /pages , /pages/Documentation and /pages/Documentation/Habr .
If the user can view the page, then access the file on disk, read its contents and display it.
Articles
For conversion, a library for Ruby , which is called kramdown - all its features are also supported.
After generating the HTML, the markup is embedded in the prepared template, where the generated navigation is still embedded.
Generating navigation works quite simply - a complete list of all files and folders is obtained recursively, then they are filtered by user rights, and the resultant structure is already placed on the template.
The search works just as well.
For decoration, I used materialize , styles from the Kotlin documentation site for the articles themselves, took the ideas from the editor on the github, and so on trivially.
→ Source code available here.
I am not a NodeJS - or a backend developer, but I like to be distracted by something interesting. The article was written because I thought that the thing looks quite useful.
Yes, there are analogues with the same idea (to be honest, I learned already after development) - but they don’t have many of the above (and not described here) features, and the implementation looks more complicated: the same documentation site Kotlin knows how to execute the code and, it seems, everything, - although the project itself is rather big.
PS I did not break the rules of Habr, and apart from the link to the githab and the general description, the article does not contain. If suddenly people show interest, I can write a series of stateek with a detailed description of the whole development process or specific moments - for one article here is unlikely to succeed.