Generate HTML via make4ht

[fennecJ]

make4ht has a lot of defectors:

• When it parsing lkmpg.tex and meet \tableofcontents will throw error
• When it parsing lkmpg.tex and meet url with underscore \_, it will output \_
  directly instead of _
• TOC in generated page isn't as pretty as pdf version
• The github action script released by make4ht's team
  worked inconsistent with computer side which causing
  error when generating github page,and I currently cannot
  find a way to generate github page through github action via make4ht.
  You can see the result page in here currently.

[jserv]

Known issue: Underscores can't be used in URLs, as the underscore character is not rendered expectedly.

[jserv]

It is a directory named "docs."

[jserv]

Filename "config.cfg" is too generic. Can you use more specific one?

[jserv]

Did you use external source files such as CSS? If so, we have to mention the source and clarify the potential licensing terms.

[fennecJ]

It is a directory named "docs."

I have modified that commit message, thanks.

[fennecJ]

Did you use external source files such as CSS? If so, we have to mention the source and clarify the potential licensing terms.

I remove the whole html /directory . You can generate these files on your own with make html when needed.

[ekangmonyet]

I'm getting error when rendering the graph at 0.7.3 Manage /proc file with seq_file, is it only me?

XML Parsing Error: mismatched tag. Expected: </g>.
Location: html/lkmpg-1.svg
Line Number 5, Column 44:

[fennecJ]

I'm getting error when rendering the graph at 0.7.3 Manage /proc file with seq_file, is it only me?

XML Parsing Error: mismatched tag. Expected: </g>.
Location: html/lkmpg-1.svg
Line Number 5, Column 44:

I don't meet that problem.
You can try using
make4ht -a --debug -suf html5 -c html.cfg -d html lkmpg.tex
to dump full info when parsing the file,
maybe it will provide some hint.
Also check the version of your make4ht and tex.
using command make4ht -v and tex -v to check them.
For my environment

make4ht version v0.3h

TeX 3.141592653 (TeX Live 2021)
kpathsea version 6.3.3

[jserv]

I encountered the following errors while running make html:

[ERROR]   htlatex: Compilation errors in the htlatex run
[ERROR]   htlatex: Filename	Line	Message
[ERROR]   htlatex: ./lkmpg.tex 	42	 LaTeX Error: There's no line here to end.

Package information:

$ make4ht -v
make4ht version v0.3g
$ tex -v | head -1
TeX 3.141592653 (TeX Live 2021)

[fennecJ]

I encountered the following errors while running make html:

[ERROR]   htlatex: Compilation errors in the htlatex run
[ERROR]   htlatex: Filename	Line	Message
[ERROR]   htlatex: ./lkmpg.tex 	42	 LaTeX Error: There's no line here to end.

Package information:

$ make4ht -v
make4ht version v0.3g
$ tex -v | head -1
TeX 3.141592653 (TeX Live 2021)

Yes, as I mentioned.
When it parsing lkmpg.tex and meet \tableofcontents will throw error
And line 42 is \tableofcontents
But it can still generate html files

[jserv]

I found a workaround to turn off TOC while generating HTML:

--- a/lkmpg.tex
+++ b/lkmpg.tex
@@ -39,7 +39,12 @@
 \begin{document}
 
 \maketitle
+
+\ifdefined\HCode
+% turn off TOC
+\else
 \tableofcontents
+\fi
 
 \section{Introduction}
 \label{sec:introduction}

Then, I got the message:

[STATUS] make4ht: Conversion finished

[fennecJ]

I found a workaround to turn off TOC while generating HTML:

--- a/lkmpg.tex
+++ b/lkmpg.tex
@@ -39,7 +39,12 @@
 \begin{document}
 
 \maketitle
+
+\ifdefined\HCode
+% turn off TOC
+\else
 \tableofcontents
+\fi
 
 \section{Introduction}
 \label{sec:introduction}

Then, I got the message:

[STATUS] make4ht: Conversion finished

That way worked for me too.
However it cause the output html files without TOC.
And I found a way to add back TOC according to this

--- a/html.cfg
+++ b/html.cfg
@@ -1,5 +1,7 @@
 \Preamble{xhtml}
 
+\Configure{tableofcontents*}{chapter,section,subsection}
+

And the generated html files contains TOC again

[Hsins]

@fennecJ

I think that you misunderstood something about GitHub Page and make4ht-action.

The Workflow Matters

Let's see the sample main.yml file given by make4ht-action.

name: CI 
on: [push] 
jobs: 
  build: 
   runs-on: ubuntu-latest 
   steps: 
   - uses: actions/checkout@v1 
   - name: Run make4ht 
     uses: docker://ghcr.io/michal-h21/make4ht-action:latest 
     env: 
       command: "make4ht -d out main.tex" 
   - name: Publish the web pages 
     uses:  peaceiris/actions-gh-pages@v3 
     with: 
       github_token: ${{ secrets.GITHUB_TOKEN }} 
       publish_dir: ./out 

The workflow do the following tasks whenever there's any "push" event in the repository:

1. Pull and use the docker image docker://ghcr.io/michal-h21/make4ht-action:latest.
2. Run the command "make4ht -d out main.tex". This would convert main.tex to main.html and save it in the ./out directory.
3. Run the actions-gh-pages workflow. This would deploy the files inside publish_dir folder (which set to the ./out folder in this case) to GitHub Pages.

What Should We Do

There're things to be concerned:

• The environments (operating system) used by GitHub Actions for executing workflows DON'T have any dependencies (such as texlive, dvipng and also make) be pre-installed.
• Though the make4ht-action workflow packs an environment as docker image, it also DON'T have dvipng be pre-installed (it's a pity that dvipng is essential for us).

I create a simple deploy-site.yml here for reference and you can check the created site by visiting https://hsins-fork.github.io/lkmpg/lkmpg.html.

name: Generate HTML and deploy to GitHub Page.

on:
  push:
    branches:
      - master

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: checkout branch
        uses: actions/checkout@v2

      - name: install dependencies
        run: |
          sudo apt update
          sudo apt install make texlive-full dvipng
          make html

      - name: deploy site
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./html                                          # --> should be the same as your output folder of make4ht
          publish_branch: gh-pages

Note that:

• GitHub Page find index.html in the folder.. Now our output file is lkmpg.html so that the URL would be https://hsins-fork.github.io/lkmpg/lkmpg.html instead of https://hsins-fork.github.io/lkmpg/.
• It's not a good practice to hardcode something like sudo apt update and sudo apt install make texlive-full dvipng in the workflow config *.yml file. (try to build the docker image for our repository). Besides, consider just install the packages in need:

  # (X) texlive-all is too fat and slow down the workflow
  $ sudo apt install texlive-full
  # (O) just install the packages in need
  $ sudo apt install texlive texlive-extra-utils

• GitHub Pages is designed to host pages from a GitHub repository. And the repository owner (@jserv) need to setup the source branch and folder in Settings > Pages.

[fennecJ]

Thanks for @Hsins ’s reply.
I indeed don’t understand github action very well.
I’ll try your script tomorrow.
And for the link issue, according to the document.
I currently don't find a way to assign the output filename when using make4ht
Maybe add
mv ./html/lkmpg.html ./html/index.html into Makefiles?

[fennecJ]

@Hsins
I checked the site you generated.
And it looks like several code blocks cannot rendered correctly.
If you run the script on computer side, the result should be looks like
this

[ekangmonyet]

@Hsins
I checked the site you generated.
And it looks like several code blocks cannot rendered correctly.
If you run the script on computer side, the result should be looks like
this

What about texlive docker container? This is the locally docker-built version:
https://ekangmonyet.github.io/lkmpg_page_test/lkmpg.html
Or manually install a texlive instead of using the one in ubuntu repository so we have full control over it ...?

Btw I notice that the svg rendered at 0.7.3 is corrupted (both yours and mine):

[fennecJ]

@ekangmonyet
Thanks for inform me about corrupted svg.
I just fix that and it rendered correctly now.
lkmpg
As for the container issue, I'll try it in some days.

[jserv]

Rebase the latest master branch where I removed out-of-date kernel versioning scheme.

[jserv]

Use "git rebase -i" to rework/squash git commits in preparation for the merging.

[jserv]

Always use "directory" instead of "folder."
We prefer UNIX flavors.

[jserv]

Improve the git commit messages.
See https://chris.beams.io/posts/git-commit/

[jserv]

Improve the grammar in git commit message. You shall address the motivation and/or the problem you are going to solve at first glance. Then, explain how this patch works.

[jserv]

Thank @fennecJ for contributing! I amended the commit messages slightly.

[fennecJ]

Thanks for applying my PR, I indeed learned a lot during the discussion.