checkpoint add initial inc/md2html.cfg file
Adjust HTML phase names and filenames under inc. Improve phase documentation in inc/README.md. Added inc/md2html.cfg as an initial markdown to HTML configuration file. The inc/md2html.cfg file is undergoing design evaluation and thus may change. Nevertheless the comments in inc/md2html.cfg give some hints as to how HTML files will be formed from markdown files.
This commit is contained in:
Landon Curt Noll committed
1 parent
b35f9a4f46
commit
8293980298
16 files changed
+293
-60
No files matched your search
+49
-26
@@ -32,40 +32,63 @@ The canonical way that HTML content is built uses, by default, files of the form
|
||||
*.default.html
|
||||
```
|
||||
|
||||
The following is the canonical order for building HTML content from a winner `README.md` file:
|
||||
|
||||
0. top.default.html
|
||||
1. head.default.html
|
||||
2. body.default.html
|
||||
3. before-row.default.html
|
||||
4. page-top.default.html
|
||||
5. topnav.default.html
|
||||
6. before-row.default.html
|
||||
7. before-leftcolumn.default.html
|
||||
8. sidenav.default.html
|
||||
9. before-rightcolumn.default.html
|
||||
10. before-content.default.html
|
||||
### HTML phases
|
||||
|
||||
At this point, page content such as that produced sources such as authot JSON and
|
||||
markdown converyerd by the `pandoc` tool is inserted.
|
||||
The following HTML phase files are used to build HTML content:
|
||||
|
||||
This is followed by canonical order for the end of the HTML content:
|
||||
0. inc/top.default.html
|
||||
1. inc/head.default.html
|
||||
2. inc/body.default.html
|
||||
3. inc/header.default.html
|
||||
4. inc/topnav.default.html
|
||||
5. inc/begin-row.default.html
|
||||
6. inc/begin-leftcolumn.default.html
|
||||
7. inc/sidenav.default.html
|
||||
8. inc/end-leftcolumn.default.html
|
||||
9. inc/begin-rightcolumn.default.html
|
||||
10. inc/before-content.default.html
|
||||
|
||||
11. after-content.default.html
|
||||
12. after-rightcolumn.default.html
|
||||
13. after-row.default.html
|
||||
14. page-bottom.default.html
|
||||
15. bottom.default.html
|
||||
Phases 11-19 are reserved for future use.
|
||||
|
||||
20. <<insert before pandoc tool output>>
|
||||
21. <<insert pandoc tool output>>
|
||||
22. <<insert after pandoc tool output>>
|
||||
|
||||
Phases 23-29 are reserved for future use.
|
||||
|
||||
30. inc/after-content.default.html
|
||||
31. inc/end-rightcolumn.default.html
|
||||
32. inc/end-row.default.html
|
||||
33. inc/footer.default.html
|
||||
34. inc/bottom.default.html
|
||||
|
||||
Phases 35-39 are reserved for future use.
|
||||
|
||||
In the above HTML phases, except HTML phases 20-29, symbols of the form %%TOKEN%% are substituted.
|
||||
|
||||
|
||||
### Tool command line
|
||||
|
||||
The command line of a [build-ioccc repo](https://github.com/ioccc-src/build-ioccc/tree/master)
|
||||
tool, and perhaps modified via [md2html config file](/inc/md2html.cfg) file may change
|
||||
to using a different filename for a given phase. For example when forming the HTML
|
||||
from `2020/ferguson2/chocolate-cake.md`, a different "topnav" navigation bar is needed. So instead of the usual top navigation bar that normally directs people to the previous entry for the year, or go up to the year page, or to the next entry for the year, a top navigation bar to just go up to the entry's main page is needed. So the line for `2020/ferguson2/chocolate-cake.md` would reference `topnav.up2index.html` instead of using the `topnav.default.html` default.
|
||||
to using a different filename for a given phase.
|
||||
|
||||
In some cases the [md2html config file](/inc/md2html.cfg) may disable forming HTML content from a givrn markdown file altogether.
|
||||
For example when forming the HTML from `2020/ferguson2/chocolate-cake.md`,
|
||||
a different "topnav" navigation bar is needed. So instead of the
|
||||
usual top navigation bar that normally directs people to the previous
|
||||
entry for the year, or go up to the year page, or to the next entry
|
||||
for the year, a top navigation bar to just go up to the entry's
|
||||
main page is needed. A line the [md2html config file](/inc/md2html.cfg) file
|
||||
that refers to `2020/ferguson1/chocolate-cake.md` may specify use
|
||||
of `topnav.up2index.html` instead of using the `topnav.default.html` default.
|
||||
|
||||
In above mentioned canonical order, a phase may be skipped by an entry in the [md2html config file](/inc/md2html.cfg) by referring a
|
||||
phaee file ending in ".none.html". Files of the form will **NOT** exist, instead the tool will skip using such a file:
|
||||
In some cases the [md2html config file](/inc/md2html.cfg) may disable forming HTML content from a givrn markdown file altogether.
|
||||
|
||||
In above mentioned canonical order, a phase may be skipped by an
|
||||
entry in the [md2html config file](/inc/md2html.cfg) by referring
|
||||
a phase file ending in ".none.html". Files of the form will **NOT**
|
||||
exist, instead the tool will skip using such a file:
|
||||
|
||||
```
|
||||
*.none.html
|
||||
@@ -194,4 +217,4 @@ content with JavaScript disabled.
|
||||
|
||||
The IOCCC will **NOT MANDATE USE OF JavaScript** to view [official IOCCC web site](https://www.ioccc.org).
|
||||
|
||||
For this reason, we cannot use JavaScript include HTML content.
|
||||
For this reason, we cannot use JavaScript include HTML content.
|
||||
@@ -1,5 +0,0 @@
|
||||
<!-- START: this line start content from: /inc/after-rightcolumn.default.html -->
|
||||
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/after-rightcolumn.default.html -->
|
||||
@@ -1,5 +0,0 @@
|
||||
<!-- START: this line start content from: /inc/after-row.default.html -->
|
||||
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/after-row.default.html -->
|
||||
@@ -1,5 +0,0 @@
|
||||
<!-- START: this line start content from: /inc/before-leftcolumn.default.html -->
|
||||
|
||||
<div class="leftcolumn">
|
||||
|
||||
<!-- END: this line ends content from: /inc/before-leftcolumn.default.html -->
|
||||
@@ -1,5 +0,0 @@
|
||||
<!-- START: this line start content from: /inc/before-rightcolumn.default.html -->
|
||||
|
||||
<div class="rightcolumn">
|
||||
|
||||
<!-- END: this line ends content from: /inc/before-rightcolumn.default.html -->
|
||||
@@ -1,5 +0,0 @@
|
||||
<!-- START: this line start content from: /inc/before-row.default.html -->
|
||||
|
||||
<div class="row">
|
||||
|
||||
<!-- END: this line ends content from: /inc/before-row.default.html -->
|
||||
@@ -0,0 +1,5 @@
|
||||
<!-- START: this line start content from: /inc/begin-leftcolumn.default.html -->
|
||||
|
||||
<div class="leftcolumn">
|
||||
|
||||
<!-- END: this line ends content from: /inc/begin-leftcolumn.default.html -->
|
||||
@@ -0,0 +1,5 @@
|
||||
<!-- START: this line start content from: /inc/begin-rightcolumn.default.html -->
|
||||
|
||||
<div class="rightcolumn">
|
||||
|
||||
<!-- END: this line ends content from: /inc/begin-rightcolumn.default.html -->
|
||||
@@ -0,0 +1,5 @@
|
||||
<!-- START: this line start content from: /inc/begin-row.default.html -->
|
||||
|
||||
<div class="row">
|
||||
|
||||
<!-- END: this line ends content from: /inc/begin-row.default.html -->
|
||||
@@ -0,0 +1,5 @@
|
||||
<!-- START: this line start content from: /inc/end-leftcolumn.default.html -->
|
||||
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/end-leftcolumn.default.html -->
|
||||
@@ -0,0 +1,5 @@
|
||||
<!-- START: this line start content from: /inc/end-rightcolumn.default.html -->
|
||||
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/end-rightcolumn.default.html -->
|
||||
@@ -0,0 +1,5 @@
|
||||
<!-- START: this line start content from: /inc/end-row.default.html -->
|
||||
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/end-row.default.html -->
|
||||
@@ -1,14 +1,10 @@
|
||||
<!-- START: this line start content from: /inc/page-bottom.default.html -->
|
||||
<!-- START: this line start content from: /inc/footer.default.html -->
|
||||
|
||||
<div class="footer">
|
||||
|
||||
<hr>
|
||||
|
||||
<h2>Footer</h2>
|
||||
|
||||
<p>This is where stuff at the bottom of all pages would be found.</p>
|
||||
|
||||
<a href="#top">Jump to top</a>
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/page-bottom.default.html -->
|
||||
<!-- END: this line ends content from: /inc/footer.default.html -->
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- START: this line start content from: /inc/page-top.default.html -->
|
||||
<!-- START: this line start content from: /inc/header.default.html -->
|
||||
|
||||
<div class="header">
|
||||
<img src="%%DOCROOT_URL_SLASH%%png/ioccc.png" alt="IOCCC image by Matt Zucker" width=300 height=110>
|
||||
@@ -6,4 +6,4 @@
|
||||
<h2>%%HEADER_2%%</h2>
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/page-top.default.html -->
|
||||
<!-- END: this line ends content from: /inc/header.default.html -->
|
||||
+210
@@ -0,0 +1,210 @@
|
||||
#
|
||||
# md2html.cfg - markdown to HTML configuration
|
||||
|
||||
##########
|
||||
# syntax #
|
||||
##########
|
||||
|
||||
# Comments start with a # symbol and continue to the end of the line.
|
||||
|
||||
# Lines are of the form (without any leading whitespace or # of course):
|
||||
#
|
||||
# file_glob [cfg_options ..]
|
||||
#
|
||||
# where "file_glob" is a Bash Extended Glob (not a regular expression).
|
||||
# and where "cfg_options .." are zero or more configuration file options.
|
||||
#
|
||||
# File paths are evaluated from the top of the repo. A leading / in a file_glob
|
||||
# is assumed to be under the topdir directory.
|
||||
#
|
||||
# For information on Bash Extended Globbing, see:
|
||||
#
|
||||
# https://www.linuxjournal.com/content/bash-extended-globbing
|
||||
# https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html
|
||||
#
|
||||
# For a given file, the first "file_glob" Bash Extended Glob that matches is used.
|
||||
# If no "file_glob" matches, the file is ignored.
|
||||
#
|
||||
# Any "options.." are processed between the options from the command line
|
||||
# and any filename arguments on the command line. For example:
|
||||
#
|
||||
# command [command_options ..] [cfg_options ..] [--] [filename_arg ..]
|
||||
#
|
||||
# Here the "command" first processes any command line options, then
|
||||
# any cfg_options from this file from a 1st match of a given file_glob,
|
||||
# followed by an optional -- and then zero of more filename_arg arguments.
|
||||
|
||||
##################
|
||||
# import options #
|
||||
##################
|
||||
|
||||
# While options might vary from command to command, there are some
|
||||
# common options are required by tools that use this configuration file:
|
||||
#
|
||||
# -h print help message and exit
|
||||
# -v level set verbosity level (def level: 0)
|
||||
# -V print version string and exit
|
||||
#
|
||||
# -n go thru the actions, but do not update any files (def: do the action)
|
||||
# -N do not process file, just ignore the file (def: process the file)
|
||||
#
|
||||
# -C dir cd dir (def: cd to "git rev-parse --show-cdup"
|
||||
# if "git rev-parse --is-inside-work-tree" is true)
|
||||
# -d topdir set topdir (def: if "git rev-parse --is-inside-work-tree" is true
|
||||
# use output of "git rev-parse --show-toplevel")
|
||||
# -i dir inc files are under topdir/dir (def: inc files are under topdir/inc)
|
||||
#
|
||||
# -D def "def" is default HTML phase name (def: "default" is default phase name)
|
||||
#
|
||||
# -H phase=name Use "phase.name.html" for HTML phase (def: use phase.default.html)
|
||||
# -H phase=none Disable processing for HTML phase "phase" (def: process HTML phase)
|
||||
#
|
||||
# -b tool before pandoc processing, add tool to in HTML phase 20 (def: do not output before pandoc)
|
||||
# -B option run the "before tool" with option (def: do not add any options)
|
||||
#
|
||||
# -p pandoc path to pandoc used in HTML phase 21 (def: use "type -P pandoc" for pandoc path)
|
||||
# -p . disable use of pandoc, just output content (def: process with pandoc)
|
||||
# -P option run pandoc with option (def: run pandoc with: "-f markdown -t html")
|
||||
# -w do not run pandoc with "--fail-if-warnings=true") (def: use "--fail-if-warnings=true")
|
||||
#
|
||||
# -a tool after pandoc processing, add tool to in HTML phase 22 (def: do not output after pandoc)
|
||||
# -A option run the "after tool" with option (def: do not add any options)
|
||||
#
|
||||
# -s token=value substitute %%token%% with value except in HTML phases 20-29 (def: do not substitute any tokens)
|
||||
# -W failure to replace a %%token%% is not an error (def: exit a token is not substituted)
|
||||
#
|
||||
# -o tool Use the output of tool to generate option lines (def: do not)
|
||||
# -O option run the "token replace tool" with option (def: do not add any options)
|
||||
#
|
||||
# -e exitcode force exit with exitcode (def: exit based on success or failure of the action)
|
||||
#
|
||||
# The output from "-b tool" will be used in HTML phase 20 before pandoc processing.
|
||||
# The output from pandoc (unless -p .) will be used HTML phase 21.
|
||||
# The output from "-a tool" will be used in HTML phase 22 after pandoc processing.
|
||||
#
|
||||
# The output from "-o tool" is zero or more cfg_options as if they were found in this configuration file.
|
||||
# The intent of "-o tool" is to output 0 or more "-t token=value" options. The "option tool" may
|
||||
# output other options, any output if another "-o tool" or another "-O option" will be ignored.
|
||||
#
|
||||
# The "tool" path (for -b tool, -a tool, -o tool), if not absolute, is assumed to be under topdir.
|
||||
#
|
||||
# A "tool" (for -b tool, -a tool, -o tool) is given the path of the file that matched the "file_glob"
|
||||
# (see above) as an argument. File the argument, any "options" (see -B opton, -A option, -O option)
|
||||
# are added to the "tool" command line.
|
||||
#
|
||||
# While above list is not a complete list of options, it does list options that are required of
|
||||
# tools that use this configuration file.
|
||||
|
||||
###############
|
||||
# HTML phases #
|
||||
###############
|
||||
|
||||
# The following HTML phase files are used to build HTML content:
|
||||
#
|
||||
# 0. inc/top.default.html
|
||||
# 1. inc/head.default.html
|
||||
# 2. inc/body.default.html
|
||||
# 3. inc/header.default.html
|
||||
# 4. inc/topnav.default.html
|
||||
# 5. inc/begin-row.default.html
|
||||
# 6. inc/begin-leftcolumn.default.html
|
||||
# 7. inc/sidenav.default.html
|
||||
# 8. inc/end-leftcolumn.default.html
|
||||
# 9. inc/begin-rightcolumn.default.html
|
||||
# 10. inc/before-content.default.html
|
||||
#
|
||||
# Phases 11-19 are reserved for future use.
|
||||
#
|
||||
# 20. <<insert before pandoc tool output>>
|
||||
# 21. <<insert pandoc tool output>>
|
||||
# 22. <<insert after pandoc tool output>>
|
||||
#
|
||||
# Phases 23-29 are reserved for future use.
|
||||
#
|
||||
# 30. inc/after-content.default.html
|
||||
# 31. inc/end-rightcolumn.default.html
|
||||
# 32. inc/end-row.default.html
|
||||
# 33. inc/footer.default.html
|
||||
# 34. inc/bottom.default.html
|
||||
#
|
||||
# Phases 35-39 are reserved for future use.
|
||||
#
|
||||
# In the above HTML phases, except HTML phases 20-29, symbols of the form %%TOKEN%% are substituted.
|
||||
|
||||
#################
|
||||
# Configuration #
|
||||
#################
|
||||
|
||||
# top level markdown files have no top navigation bar
|
||||
|
||||
/CODE_OF_CONDUCT.md -H topnav=none -o inc/subst.default.sh
|
||||
/README.md -H topnav=none -o inc/subst.default.sh
|
||||
/bugs.md -H topnav=none -o inc/subst.default.sh
|
||||
/contact.md -H topnav=none -o inc/subst.default.sh
|
||||
/faq.md -H topnav=none -o inc/subst.default.sh
|
||||
/index.md -H topnav=none -o inc/subst.default.sh
|
||||
/judges.md -H topnav=none -o inc/subst.default.sh
|
||||
/news.md -H topnav=none -o inc/subst.default.sh
|
||||
/thanks-for-fixes.md -H topnav=none -o inc/subst.default.sh
|
||||
/winners.md -H topnav=none -o inc/subst.default.sh
|
||||
/www-history.md -H topnav=none -o inc/subst.default.sh
|
||||
/years.md -H topnav=none -o inc/subst.default.sh
|
||||
|
||||
# year level README.md files have a special year navbar
|
||||
|
||||
/[12][0-9][0-9][0-9]/README.md -H topnav=year -o inc/subst.default.sh -o inc/subst.year.sh
|
||||
/mock/README.md -H topnav=mock_year -o inc/subst.default.sh
|
||||
|
||||
# Navigation bar only moved up to the index for internal markdown files
|
||||
|
||||
/1986/marshall/compilers.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1991/brnstnd/sorta.README.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1992/buzzard.2/buzzard.2.README.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1993/ejb/hanoi.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1993/ejb/patience.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1993/rince/design.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1994/shapiro/shapiro.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1995/leo/spoiler1.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1998/dorssel/dorssel.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/1998/schweikh1/macos.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2004/gavin/gavin.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2012/deckmyn/deckmyn.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2012/hou/hint.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2012/tromp/how.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2013/hou/doc/example.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2014/endoh1/spoilers.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2015/burton/spoilers.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2018/burton2/discrepancies.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2018/ferguson/rpm.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/endoh2/spoiler/spoiler.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/COMPILING.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/HACKING.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/bugs.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/cannibalism.log.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/chocolate-cake.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/crazy.log.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/gameplay.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/spoilers.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/terminals.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson1/troubleshooting.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson2/chocolate-cake.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson2/obfuscation.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/2020/ferguson2/recode.md -H topnav=up2index -o inc/subst.default.sh
|
||||
|
||||
# All winner inventory.md files use a navbar that just moved to the index
|
||||
|
||||
/[12][0-9][0-9][0-9]/*/inventory.md -H topnav=up2index -o inc/subst.default.sh
|
||||
/mock/*/inventory.md -H topnav=up2index -o inc/subst.default.sh
|
||||
|
||||
# Unless matched above, default process all winner README.md files
|
||||
|
||||
/[12][0-9][0-9][0-9]/*/*.md -o inc/subst.default.sh -o inc/subst.readme.sh
|
||||
/mock/*/*.md -o inc/subst.default.sh -o inc/subst.readme.sh
|
||||
|
||||
# Exit 9 for any markdown file that we have not previously configured
|
||||
|
||||
*.md -e 9
|
||||
|
||||
# Last, everything else is silently ignored
|
||||
|
||||
* -N
|
||||
@@ -27,6 +27,5 @@
|
||||
<div class="sidenav">
|
||||
<a href="#top">Jump to top</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- END: this line ends content from: /inc/sidenav.default.html -->
|
||||
Reference in new issue
Block a user