In order to make a consistent, nice-looking website, you will want various features (navigation bar, 88x31 badges, etc.) to appear identical on several pages. The basic way to do this is to write the same HTML elements in all of your pages. The problem with this approach is that it is time-consuming, and if you want to edit the repeated features, you will need to change them in every file!
If you host your own site, you can use server-side programming languages such as SSI (server-side includes) so that when the user requests the page, the server automatically inserts the required HTML element. The trouble with this is that sites like Neocities do not support SSI.
As detailed in this article on "client-side includes", you can use JavaScript to achieve the same sort of thing, with the work of insertion being done in the user's browser. But the trouble with this is it requires a browser that supports JavaScript. So as per my principle of no unnecessary JavaScript, I must find another way.
If client-side includes reduce accessibility and server-side includes are unavailable, we need to include the common elements in every file. But as stated before, that becomes impractical the more pages are added, so we need to make this easier to do.
Here is an example directory structure for a website using XFWK:
The source files (that the user edits) are stored in site/. When the user wants to publish the site, they run XFWK and the website is compiled into site.o/ and this is what is uploaded to the host (using the neocities command-line tool).
This user has a consistent navigation bar and footer that they want to use on all their pages. In (for example) index.html, they put the tags <fwk:include file="navigation.html" /> and <fwk:include file="footer.html" /> in the correct places. In ?includes/navigation.html there is a single <html> tag containing the elements to make the navigation bar. At compile time, these are inserted into the files.
This user also has a blog where the <body> of each page is mostly the same, except for different content. In each source file for the blog, rather than the usual <body> tag, the user writes a <fwk:include file="blog-body.html"> tag wrapping the contents of the article. ?includes/navigation.html contains a <fwk:inner> tag. At compile time, the <fwk:inner> tag is replaced with the content of the <fwk:include> tag and the whole thing is inserted into the page.
The program consists of two files, xfwk and xfwk-replacer. xfwk-replacer is written in Python and converts all custom tags in a single file. xfwk is written in fish-shell and iterates over the source directory, converting all HTML files, and copying everything else except ?includes and other special files.
xfwk-replacer was originally written using the module Beautiful Soup, but that module really messed with the formatting of the HTML and made the compiled files almost unreadable; it also messed around with the whitespace, causing spaces to appear in places where they shouldn't. I rewrote it using ElementTree and it now behaves sensibly and even leaves the formatting alone!
New tag: <fwk:script file="filename"> - process the inner text / HTML using a specified script in the ?scripts directory.
Before I do a public release I will need to work out how to use Github or whatever.
