From 4be8a62eacf0fc2a2632c7e4708d578a61a141b7 Mon Sep 17 00:00:00 2001 From: Adrian Kummerlaender Date: Sun, 12 Oct 2014 15:22:29 +0200 Subject: Updated website project page and added StaticXSLT page * this was done to match the recent extraction of the generic static site generation framework into a separate project --- source/00_content/pages/projects/static_xslt.md | 55 ++++++++++++++++++++++++ source/00_content/pages/projects/this_website.md | 29 ++++--------- 2 files changed, 63 insertions(+), 21 deletions(-) create mode 100644 source/00_content/pages/projects/static_xslt.md (limited to 'source') diff --git a/source/00_content/pages/projects/static_xslt.md b/source/00_content/pages/projects/static_xslt.md new file mode 100644 index 0000000..3615244 --- /dev/null +++ b/source/00_content/pages/projects/static_xslt.md @@ -0,0 +1,55 @@ +# StaticXSLT + +…is the XSLT based static site generation framework especially developed to generate this website. + +Its MIT licensed source code is available both [Github] and [cgit]. + +The implementation of a pure[^1] XSLT solution to the problem of static site generation required the development of a collection of external functions enabling access to the filesystem, external applications and other transformations from inside XSLT. These external functions are not part of this project and were developed separately as [InputXSLT]. Additionally a basic XSLT build system was developed to make _StaticXSLT_ usable for different projects which is available as [BuildXSLT]. + +The prime example of how this framework may be used in practice is the implementation of [this website]. + +## Overview + +The implementation of the static site generator is contained within the `src/steps` directory of the linked repository and consists of four XSL transformations that all form a link in the generation chain module executed by [BuildXSLT]. + +These transformations traverse the given source directory, plan tasks[^2] to be executed, process those tasks and summarize the result for the user. + +~~~ +common:~# ixslt --input make.xml --transformation ../BuildXSLT/build.xsl +Tasks processed: 19 +Tasks successful: 19 +▶ Generation successful. +common:~# +~~~ + +The first of these transformations `list.xsl` traverses and lists a `source` directory containing various _levels_ depicting the different stages of the actual static site generation process as a base for all further processing. + +Based on the results of the `list.xsl` transformation the next transformation `plan.xsl` schedules a number of different tasks to be processed by `process.xsl`. Examples for these tasks are cleaning a `target` directory, linking files and folders and of course generating transformation stylesheets contained within the various _levels_ of the `source` tree. + +After the various tasks are processed by `process.xsl` the results of all tasks are summarized by `summarize.xsl` to provide the user with a easy to read plain-text output. + +## Levels + +A _level_ is simply a folder within a given `source` directory which may in turn contain a arbitrary number of transformations and source documents inside subfolders. All transformations within these _levels_ are processed by the _StaticXSLT_ transformation chain which handles datasource dependency resolution and preserves the correct result path context. _Levels_ are processed according to their alphabetic order. Subfolders of _level_ directories that do not contain any XSLT stylesheets and non-stylesheet files are automatically symlinked to their appropriate target directory. + +## Data Source and target resolution + +Every transformation contained in one of the _levels_ contains a `meta` variable defining the required data sources and target paths. This information is read during task processing by the `process.xsl` transformation and used to provide each transformation with the data sources it requires and write the output to the path it desires. This definition of requirements and targets directly inside each transformation is an essential part of how this static site generation concept works. + +The system currently provides a couple of different data source reading modes such as `full` for reading a complete XML file as input, `iterate` for iterating the second-level elements of a given XML source and `expression` for evaluating a arbitrary XPath expression against a given XML file. Target modes include `plain` for writing a the result into a given file at the appropriate target level and `xpath` for evaluating a XPath expression to generate the target path. This XPath evaluation functionality in combination with the `iterate` data source mode is especially helpful in situations where one wants to generate multiple output files from a single transformation such as when generating article pages or the pages of the article stream. + +## Differentiation and limitations + +This approach to static site generation is novel in the manner that it is the only publicly available XSLT based solution to this problem domain that I am aware of, which uses XSLT as both the application and template language. I extended XSLT with [InputXSLT] and developed this static site generation in the attempt of producing something as flexible as [Symphony CMS] that generates static output. + +The current implementation of the concept described on this page is limited in the sense that it doesn't support incremental regeneration but generates the whole website from scratch on each run. While this problem should also be solvable in pure XSLT, I currently do not plan on solving it as it is fast enough for my current use cases and largely depends on the speed of the used Markdown processor and syntax highlighter anyway. + +[^1]: Pure as in all templates, data source aggregation and the generation logic itself is implemented in XSLT. Tasks like e.g. syntax highlighting and Markdown processing are still handled by external programs called from within XSLT. +[^2]: Tasks include cleaning directories, generating transformations and symlinking directories and files into the target directory + +[Github]: https://github.com/KnairdA/StaticXSLT/ +[cgit]: http://code.kummerlaender.eu/StaticXSLT/ +[BuildXSLT]: /page/build_xslt/ +[InputXSLT]: /page/input_xslt/ +[this website]: /page/this_website/ +[Symphony CMS]: http://getsymphony.com diff --git a/source/00_content/pages/projects/this_website.md b/source/00_content/pages/projects/this_website.md index ba083b6..4e252d5 100644 --- a/source/00_content/pages/projects/this_website.md +++ b/source/00_content/pages/projects/this_website.md @@ -1,38 +1,25 @@ # blog.kummerlaender.eu -…is the XSLT based static site generator especially developed to generate this website. +…is the set of XSLT transformations used to generate this website. Its MIT licensed source code is available both [Github] and [cgit]. -The implementation of a pure[^1] XSLT solution to the problem of static site generation required the development of a collection of external functions enabling access to the filesystem, external applications and other transformations from inside XSLT. These external functions are not part of this project and were developed separately as [InputXSLT]. +This implementation of XSLT based solution to the problem of static site generation depends on a collection of different projects such as [InputXSLT] which adds additonal functionality to XSLT through external functions, [BuildXSLT] which implements a basic XSLT build system and [StaticXSLT] which implements a generic static site generation framework as a module for the build system. ## Overview -The implementation of the static site generator contained within the `detail` directory of the linked repository and consists of four XSL transformations that all form a link in the generation chain executed by [BuildXSLT]. +The first level `00_content` contains the actual content source of the blog to be generated. This includes articles and pages formatted in Markdown and meta-data such as the page title, public URL and primary author in `meta.xml`. It is notable that this first level doesn't contain any actual transformations and as such only provides a way to store the input to _levels_ further down the processing pipeline. -These transformations traverse the given source directory, plan tasks[^2] to be executed, process those tasks and summarize the result for the user. +The second level `01_data` reads the contents of the `00_content` level and generates data sources for articles, pages and tags. These data sources contain e.g. the augmented contents of articles already converted from Markdown into _XHTML_ and separated into title, data and content areas. -~~~ -common:~# ixslt --input make.xml --transformation ../BuildXSLT/build.xsl -Tasks processed: 19 -Tasks successful: 19 -▶ Generation successful. -common:~# -~~~ +The third level `02_meta` further augments and groups these data sources. For example articles are grouped by year, tags and categories are resolved and augmented with article data provided by the previous level and articles are paginated in preparation for generating the primary article stream. -The source directory is structured into separate levels that are processed sequentially according to their name. The first level contains all actual contents of the website which are read into separate article, page and tag data sources in the data level. After the base data sources are generated further meta data sources are aggregated by the meta level. Finally the actual _XHTML_ pages are generated by the transformations contained within the result level. It is important to note that most of these links in the generation chain are created dynamically by the static site generator, i.e. the required data sources of each transformation are determined based on meta tags inside of the stylesheets themselves and there is no fixed limit of how many levels the system is able to process. - -## Differentiation and limitations - -This approach to static site generation is novel in the manner that it is the only publicly available XSLT based solution to this problem domain that I am aware of, which uses XSLT as both the application and template language. I extended XSLT with [InputXSLT] and developed this static site generation in the attempt of producing something as flexible as [Symphony CMS] that generates static output. - -The current implementation of the concept described on this page is limited in the sense that it doesn't support incremental regeneration but generates the whole website from scratch on each run. While this problem should also be solvable in pure XSLT, I currently do not plan on solving it as it is fast enough for my current use cases and largely depends on the speed of the used Markdown processor and syntax highlighter anyway. - -[^1]: Pure as in all templates, data source aggregation and the generation logic itself is implemented in XSLT. Tasks like e.g. syntax highlighting and Markdown processing are still handled by external programs called from within XSLT. -[^2]: Tasks include cleaning directories, generating transformations and symlinking directories and files into the target directory +Last but not least the fourth level `99_content` takes all the data sources generated in lower _levels_ and generates the actual website pages. [Github]: https://github.com/KnairdA/blog.kummerlaender.eu/ [cgit]: http://code.kummerlaender.eu/blog.kummerlaender.eu/ +[module]: /page/static_xslt/ [BuildXSLT]: /page/build_xslt/ [InputXSLT]: /page/input_xslt/ +[StaticXSLT]: /page/static_xslt/ [Symphony CMS]: http://getsymphony.com -- cgit v1.2.3