Showing posts with label NPM. Show all posts
Showing posts with label NPM. Show all posts

Tuesday, August 24, 2021

Generate pdf from markdown files in a folder using markdown-pdf

I am a big fan of markdown language for writing documents. One of the scenarios we encounter using markdown is to generate a pdf file or convert the markdown files to some other format. This post is to introduce an NPM package that converts markdown files to pdf file. It is considerably old but still does the job.

markdown-pdf

markdown-pdf npm library is open source software with MIT license. They have just enough documentation as well. It can be used as a command and as a library to use from our nodejs applications.

The limitations I found are as follows.

There is no direct API to convert an entire folder of markdown (.md) files. We have to iterate the folder by ourselves and give it all the file paths. Another problem is to insert page breaks between the markdown files. But that also can be overcome by using pre-processing markdown interceptor and some css tricks.

Sample code

Enough talking. The sample code to perform the below use cases with this library is available in GitHub repo.
  • How a folder can be given to markdown-pdf as there is no direct API
  • How to preprocess markdown files
  • How to give a custom CSS file

How it works

Internally it converts the markdown to HTML by using the remarkable npm library. Once the HTML files are available, it uses the phantomjs to load the HTML in the browser then print as pdf from there. It supports custom CSS files as well. 

Now it might be clear how the line breaks are inserted into the PDF files.

Use cases

If our documentation is prepared using markdown, the pdf file can be generated using this library through the CI/CD pipelines. 

Other libraries

References

Tuesday, July 14, 2020

Dependency package management design - Single big package or atomic single responsible packages

Introduction

When our applications or the system (set of connected applications) grow, we would require separating the code into components and distribute it to the application developers. This post is discussing how to design dependencies. Big dependencies or smaller dependencies

Importance of dependency management system

Though our system is not big, it is good to adopt a dependency management system. Also good to channel the public dependencies too the same repository of packages. Some reasons, not a complete list below
  • It helps to have a central repo. Easy to control what versions of dependencies are allowed to use. Otherwise, later it will be difficult to understand what all dependencies are used in our organization.
  • It increases code reuse
  • Less compile time as all the dependencies don't need to be compiled with the application change. This is arguable as the application compilation requires dependency download time.
  • Easy to track usage of code by package download and decommission.

Dependency design

Now coming to the main point. When we split our code how should we split it? Should we create a single package named cross-cutting and include everything there such as logging, caching, etc... or create single responsible packages.
 CriteriaBig package Smaller single responsible packagesComments
 Package selectionLessor one package to refer to. Consumers just refer it.There may be packages doing similar things. The difference may be very less and difficulty in choosing  
Change managementConsuming developers may require only one class change. But they get full changes. This adds regression testing efforts Consumer developers need to make sure every package is up to date. 
But easy to test package version upgrade

Package release agilityHigh chance that it may follow the release of the monolith application where developers of individual classes or components in the package have to wait for green signal from other teams to release package version.Each package dev team can release at high speed.
 Package supportOnly one big team to reach out. Consumer life would be easy.Based on organization structure the package authoring teams may scatter causing consumers difficulty to get support 

What industry follows?

The leading dependency management system NPM for Node.JS generally follows the second approach of smaller packages. Every package does one thing and does it well. Often using other packages to achieve something and expose that Facade kind of API.

The .Net Nuget system was not atomic like the NPM. But with .Net Core or Future .Net it is also following the Node.JS path of separating bigger packages into small atomic.

Answer

My answer is
atomic package model where one package does one thing and does it well.
Below are the rationale
  • The industry is going agile. ie shorter release times.
  • Microservices would be the main consumers of packages. They are small and why should they carry bigger package foot prints?
If we look at one of my nuget library DotNet.Helpers, that is not following this design. It has different components even from different technologies. That package has created to store my knowledge and reusable code than evolved from large projects.

My prediction is that software industry will converge to one technology and Node.JS or its successor Deno will replace .Net for desktop and web programming. So before I am stopping .Net, I am just storing my knowledge. Its just my prediction similar to I predicted death of Silverlight and WPF.
Things may change as Blazor is emerging and it may (very less chance) get popular and .Net will survive.


Tuesday, May 7, 2019

Node-PlantUML package to automate generation of mind map diagrams

Recently I was doing some experiments with PlantUML. PlantUML is awesome. Write code and get diagrams. It is especially great tool for engineers like me who are not that good at art. One of the main trend now a days is to automate anything and obviously we can automate diagram generation from puml file. The technology to do is obviously NodeJS.

Package to generate images from .puml files

As normal in Node world, NodeJS has a package to convert puml files into images and much more. Below is the link to the NPN package.
https://www.npmjs.com/package/node-plantuml

From here, this post assumes the reader has knowledge about NodeJS and its NPM package ecosystem.

A simple problem

If there is no problem this post is not needed. The node-plantuml package generated the diagrams for most for the puml files. But not for the mind map pumls. ie which are starting with @startmindmap.

@startmindmap
* root
** 1
**_ 3
@endmindmap

Root cause

The node-plantuml uses plantuml.jar file to bundle with it is not the latest. That jar file don't have the capability to understand @startmindmap. So it fails.

Solution

node-platuml package to include the latest plantuml.jar file. As a responsible developer, who make use of other's open source work, I should give them a PR which I will be doing soon.

Workarounds

Set the path of plantuml.jar

As any other developer, the developers of this package also left option for configuring the path to jar file. They selected the environment variable mechanism to set the path. The name of environment variable is PLANTUML_HOME. If the environment variable is not there, it will take jar file from vendor folder. Below line is from the node-plant package source code.

The code to set the environment variable to a different .jar file is as follows. If we obtain the latest plantuml.jar file, we can place it somewhere and point to the same.

process.env.PLANTUML_HOME = "node_modules/node-plantuml/vendor/plantuml_new.jar";

If there are any troubles setting the path, try the below approach.

Replace old file with new

Get the latest plantuml.jar file from VS code extension called PlantUML. The location of the platuml.jar file is below.

%userprofile%\.vscode\extensions\jebbs.plantuml-2.10.9

Put the file into the node-plantuml modules folder. Location below.

..\node_modules\node-plantuml\vendor