beerst/pubdoc repository overview

pubdoc ("publish document"): Process markdown-compatible content to produce HTML presentation

Usage: pubdoc [-f from-type] [-c | -C toc-level ] [-nNrR] [-s style-URL | -S styles-file/.type] [-qvh] [source-file]

Examples:

: pubdoc                                        # Processes standard-input to generate HTML pub content, outputs to standard-output
: pubdoc myDoc.md                               # Processes myDoc.md to generate pub content, outputs to standard-output
: pubdoc -n myDoc.md                            # Generates pub file My_doc.html (based on myDoc.md level-1 heading e.g. "# My doc")
: pubdoc -r myDoc.md                            # Renames myDoc.md to My_doc.md
: pubdoc -nr myDoc.md                           # Renames myDoc.md to My_doc.md, generates My_doc.html
: pubdoc _WIP.md                                # Due to leading "_ underscore, renames _WIP.md to My_doc.md
: pubdoc -R My_doc.md                           # Normalizes markdown content of My_doc.md
: pubdoc -c My_doc.md                           # Add (default) level-3 table to generated pub content
: pubdoc -C 4 My_doc.md                         # Adds level-4 table of contents generated pub content
: pubdoc -s styles.com/myStyle.css My_doc.md    # Adds CSS reference to generated pub content
: pubdoc -S LETTER -S myStyle.css My_doc.md     # Adds contents of standard "letter" style and specified CSS file to generated pub content
: pubdoc -f csv myTable.csv                     # From CSV file, outputs HTML table

Options:

source-file       Source content file to process (default: standard-input)

-f from-type      Transform source file type specified (e.g. "CSV"; default: "markdown"); must be compatible with pandoc processing into standard markdown format
-n                Save output to title-normalized file (with type-based extension) instead of standard-output; based on first level-1 heading markdown, optionally hidden in HTML comment; default: source filename
-N                Output processed dot-content notes along with regular output (for details: "pubdoc -hd") 
-r                Rename (or save) source file (or standard-input) to title-normalized filename (automatic if source filename starts with placeholder underscore "_")
-R                Replace source file content (or standard-input) with normalized markdown
-H [head1][:h2]   Add specified level-1 and/or level-2 headings to top of normalized markdown (and so also use for normalized filenames if applicable)
                 - Alternative, best for text with colons or spaces: set headings(s) with environment variables PUBDOC_HEADING1/PUBDOC_HEADING2

-m                Output source content as normalized markdown with dot-content preserved ("markdown-plus"); supports re-processing by pubdoc
-M                Output source content as normalized standard markdown; supports processing by standard markdown processors e.g. pandoc

-c                Add table of contents for headings level 1 through 3
-C toc-level      Add table of contents for headings level 1 through specified level

-s styles-URL     Add URL (or as specified by system variable PUBDOC_CSS_URL) as CSS stylesheet reference in generated HTML; repeatable
-S styles-file    Add contents of _styles-file_ or standard style (listed below) (or as specified by system variable PUBDOC_CSS_STYLES) as inline <style>s element in generated HTML; repeatable

-q                Show minimum or no progress and summary messages
-v                Show maximum progress and summary messages
-h / -qh / -hd    Show all help, "quick help", or help with dot-content features

Features to prepare and process markdown (MD) or other pandoc-compatible source content (e.g. CSV) for publication:

- Composes level-1 heading from input file name (if no level-1 heading present)
- Normalizes MD content (using conversion from/to markdown by pandoc), saved in "...NORM.md"
- Adds or updates source file version stamp (as HTML comment)

Features of generated publication HTML:

- Adds HTML page <title> based on MD level-1 heading
- Adds CSS styles reference(s) or <style>(s), if specified
- Adds (optional) table of contents with top/back links for headings up to max level, if specified
- Transforms markdown to published HTML file with "smart" features (e.g. paired quotes)
- Adds published date version stamp (as visible HTML at end)
- Adds details about published doc generation (as HTML comment)

Convenience features:

- Outputs summary of processing results and differences between source and processed content, unless supressed by -q "quiet" option
- Option -v "verbose" outputs details of processing
- If source filename starts with placeholder underscore "_", renames source file based on normalized MD level-1 heading, if present
- Markdown heading "&[_contd_]" transforms into a "continued" heading based on prior same-level heading, with optional continuation suffix (default "cont'd")
- Available standard format <style> types, specified by "-S type", including WEB, LETTER, SYLLABUS, SLIDES_PREVIEW, SLIDES_SHOW
- "Dot-content" support for special embedded content: (details and examples: "pubdoc -hd)
  - Notes (e.g. editorial suggestions), omitted from regular published output, or output with "-N" option
  - Inline converson of of non-MD content (e.g. a CSV table), 
  - Inline comments, omitted from processing and publication

Tips: 

- Process files remain available temporarily in /tmp with these type-named prefixes: ("ls -t" for most recent)
   pubdoc_output__  pubdoc_norm__  pubdoc_std_md__  pubdoc_notes__  pubdoc_no_notes__  pubdoc_diffs__

dopubdoc: From image beerst/pubdoc, runs container command pubdoc, binds current directory, binds local directory(s), applies dorun option(s) -I -R
- Runs pubdoc with option(s) -S -n, plus runtime options and arguments
- Uses compact dorun syntax, typical default options, target command options and arguments, and enhanced execution features; requires bash shell

Usage:                   dopubdoc [dorun-opts-continued : ] command-line-continued

Runs:                    [dorun] -b -B /tmp@/tmp -I -R - ... beerst/pubdoc : pubdoc -S WEB -n ...

Installs/updates dorun:  docker run --rm [pull_opt]  beerst/dorun ... >/tmp/dorun_exec__dopubdoc

For script summary:      dopubdoc -hS :  (note trailing ":" colon)
For more about dorun:    dopubdoc -qh :

Created 2026.09.15 07:36 by: [dorun] -s 'dopubdoc:-b -B /tmp@/tmp -I -R -::' beerst/pubdoc -S WEB -n

Usage tips:
- Make script executable:                                             chmod a+x dopubdoc
- Adjust dorun runtime options, tail-delimit with colon ":"; e.g.:    dopubdoc -v -b : ...
- Preview eXecution commands with context, but don't execute:         dopubdoc -X ... : ...
- Use redirected or piped input, e.g. instead of file or terminal:    dopubdoc -I ... : ...
- Backslash-escape quoted command options (e.g. those with spaces):   dopubdoc -a 123 -b \'Hello World\'
- Force-update installed target image (if applicable):                dopubdoc -u : ...
- Force-update script's installed dorun utility:                      dopubdoc -U : ...
- Change script defaults with associated environment variables:       SCRIPT_CMD, IMAGE_SPEC, DORUN_OPTS, RUN_OPTS, DORUN_IMAGE_SPEC, DORUN_UPDATE_RUN_OPTS
- Inspect to learn or adjust specs (e.g. by "DORUN_OPTS='-b'"):       dopubdoc -S :
- (Re)install latest release of this script (if applicable):          docker run --pull always beerst/pubdoc cat dopubdoc >dopubdoc; chmod a+x dopubdoc

Summary date:               Tue Sep 15 07:40:51 PDT 2026
Help with build/deploy/release:     make help-build
Build summary:              pubdoc_summary.txt  	(or: make summary)
README markdown:            pubdoc_README.md  	(or: make readme)
Help with run/launch/admin: pubdoc_admin_help.txt  	(or: make help-admin)
makefile for admin tasks:   pubdoc_admin_makefile  	(for use on host system)

Settings from make command-line arg=value, dockerfile directives, env variables, or defaults:
  Dockerfile:               pubdoc_dockerfile  	(default: most-recently-touched file in current dir with name *[dD]ockerfile*)
  Image      VERSION:       2609150740    (default: "WIP")
  Image      NAME:          pubdoc  	(default: basename of dockerfile [first] WORKDIR)
  Base image BASE:          ubuntu  	(from dockerfile FROM)
  Docker     BUILD_ARGS:    NA=n/a        (from environment or n/a, to apply during build)
  Git        GIT_REPO:        	(from git environment or n/a; uncommitted files or n/a: )
  Docker     DOCKER_REPO:   beerst  	(required for "release" and for _remote_ "deploy", or n/a)
  Options: (typically from same-named dockerfile ARG/ENV)
    OPTS_RUN_TEST:          
    OPTS_RUN_PROD:          
    OPTS_LAUNCH_TEST:       
    OPTS_LAUNCH_PROD:       
    OPTS_SHELL_TEST:        
    OPTS_SHELL_PROD:        

Available make actions:
  build, build-clean, deploy, release, summary, help

Custom actions from dockerfile ARG/ENV or environment variables OPTS_CUSTOM_action, or applied directly by pubdoc_admin_makefile (or n/a):
  
Uncommited local changes not pushed to git repo  (or n/a):
  

Files and directories COPYed from sources to image destination (or n/a):
  pubdoc dopubdoc   /bin/
  web.css none.css letter.css syllabus.css slides_preview.css slides_show.css  /styles/
  pubdoc_README* pubdoc_dockerfile  .
 
README markdown for e.g. image/usage description in repository (or n/a):
  pubdoc_README.md