[WIP - Discussion] Command Line HTML generation

[G-Ambatte]

This PR resolves #1035.

This PR adds a /cli folder which contains process.js, a script that takes several parameters:

• input : the filename of the downloaded source of a Homebrewery brew
• output : the filename of the desired output file
• renderer : the renderer to use (valid options are "legacy" and "v3")
• overwrite : (OPTIONAL) overwrite the output file if it already exists

Defaults for these parameters can be stored in the /cli/config.json file.

The output relies on a build of the Homebrewery project having completed, as it acquires the compiled bundle.css from the /build folder.

To be perfectly clear and explicit: the output of this script is still HTML, and needs to be loaded into Chrome to be printed to PDF. Currently there is a large delay before the page loads, but I believe that this is likely due to missing asset files, rather than any rendering issue (as the render was completed offline, and the HTML is static).

---

The current purpose of this Draft PR is to create discussion about what the users and/or the developers might want from such a CLI tool, and what the expected output might look like. Similar Issues include #1035 and #802; I'm sure that there are probably more.

[G-Ambatte]

I found the cause of the speed issue - external stylesheets were being requested incorrectly, a small change to the templated HTML header has corrected this and load speeds are vastly improved.

Internal assets still are not yet accessible (e.g. page backgrounds, footer graphics, some element borders).

[G-Ambatte]

Tagging potentially related open issues:

#661
#802
#956
#1035
#1101
#2824

This also has the potential to be precursory work for the following issue:

#1926

If you agree/disagree with the inclusion of these issues, please let me know in the comments!

[calculuschild]

The current purpose of this Draft PR is to create discussion about what the users and/or the developers might want from such a CLI tool

I personally have no use for such a tool. Besides #802 and #1035, the issues I see linked here don't seem to have any relation to a CLI at all, but I may be mistaken.

I'm all for more features, but from reading those issues, it seems people are rather looking for an "export to embeddable HTML" button on the website itself.

Adding reviewers for discussion.

[5e-Cleric]

As Calculuschild, i don't see the need for such a tool, if i understand it correctly, this would be a CLI(Command Line Interface, for those too lazy to google it) to transform markdown files into html, following the syntax and all of the homebrewery.

But isn't the homebrewery itself already doing that better? by allowing real time rendering?

Furthermore, even if the tool itself went down, the repository will stay up, and the instructions to install locally are very simple.

What is the motivation behind such a tool?

If as the boss sugests, this would be to create an embeddable html, i would suggest building a system that would allow a request for a file, and deliver its html if the file has some sort of metadata option ticked, such as published.
Actually that is not so bad of an idea.

[srfraser]

What is the motivation behind such a tool?

I came looking for just this feature. When I write documents, I store them in version control, so that I can try out changes, revert to previous versions, and other useful features. So while I do use homebrewery interactively and the live rendering is immensely useful for getting things looking good, my goal is to generate the finished document from the version committed to version control. Part of that is being able to run a CI pipeline to then generate the files required, once a commit has been made - That way I know the documents are based on what was committed, not what I was last working on.

[Gazook89]

@srfraser check out this project that takes the rendering parts of HB and puts it in a VS Code extension: https://github.com/Spjak/DungeonsAndMarkdown

this allows you to use HB locally, with your own md files that can be stored anywhere, even committing them all to a git system along with other benefits.

[srfraser]

Nice, thank you for the recommendation, I should be able to cannibalise that for my needs

[poolpog]

Hello! I am looking for a feature just like this (or a POSTable Rest API that accepts a markdown file as payload and returns rendered HTML or a PDF)

Similar @srfraser I much prefer to put documentation into version control, and process the document source as needed. In addition, this allows me to do things such as programmatically generate Markdown from data, such as to create roll tables for wandering monsters or whatever.

Using a web UI is great for immediate feedback, but terrible if I want to automate document production.

[poolpog]

In case anyone else wants to use this, here's a quick writeup on how I got this to work without installing Node or NPM. On a Macbook, MacOS Monterey

NOTE: Source dir for my local markdown file in this example is: $HOME/Projects/poolpog/wandering-monster-tables/

Add Git Fork to my local repo or clone git fork as listed in that draft PR

git remote add G-Ambatte [email protected]:G-Ambatte/homebrewery.git

Checkout branch that has the CLI code

git checkout remotes/G-Ambatte/experimentalCommandLineBrewProcess

(Don't worry about the "Detached HEAD" warnings -- we aren't making any code changes)

Build local docker image with new code checkout

docker-compose build

Run node command in docker; mount local dirs for output. You'll have to specify full paths everywhere.

docker run -it --rm \
    -v $HOME/Projects/poolpog/wandering-monster-tables/:/usr/src/app/workdir homebrewery \
    node cli/process.js --input /usr/src/app/workdir/my-brew.md  \
    --output /usr/src/app/workdir/my-brew.html \
    --renderer v3 --overwrite