https://www.forester-notes.org/index/ index /index/ Forester Forester is a tool for authoring, exploring, and sharing scientific and mathematical hypertexts. It is your lab notebook, your journal, your blackboard, and the home of your lecture notes. Forester is maintained by Jon Sterling and Kento Okura. Project information Forester devlog Forester blog Presentations Release notes References Context Backlinks Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXS/ QHXS /QHXS/ Intellectual junkyards I was first inspired to create Forester after exploring the Stacks Project and realising that what I most wanted most dearly was the ability and digital space to create my own—and feeling the pain when I tried to install the essentially defunct Gerby software that runs it. Paolo Brasolin was kind enough to help me with this, by building Sheafy on top of Jekyll. I eventually reached the limits of that tool and created Forester on my own (first as a Hugo plugin, and finally as standalone OCaml software). Later I was joined by Kento Okura who has become a strong partner in designing and developing Forester. Whilst exploring the space of tools for thought, I became aware of a cluster of related and deeply inspiring ideas—starting with Andy Matuschak’s evergreen notes which led me to Niklas Luhmann’s Zettelkasten and various kinds of digital gardening. Although all these trends are slightly different and shouldn’t be conflated, the common thread is to accumulate a bunch of small topical notes over many years in hypertext. (Luhmann’s Zettelkasten was of course a physical hypertext, where hyperlinks are hand-written and addressed to locations in his card box, whereas many Zettelkästen today are digital.) Matuschak’s “evergreen” concept refers to the practice of having notes evolve and remain up to date, as opposed to scratch notes that lose salience with time. I was interested enough in the idea that I spent some time thinking about how it might be adapted to the mathematical sciences, and I wrote a manifesto of sorts on the topic: Designing tools for scientific thought. This manifesto guided the design of Forester, whose name was itself inspired by Matuschak’s writings on evergreen notes. For some time now, however, I have been noticing a great deal of friction in my own use of evergreen notes as a tool for advancing science; for this reason, I have been using my own Forest in a different way for some time now. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXT/ QHXT /QHXT/ Life in the junkyard after a few years Let me describe how someone like me predictably starts building up their forest. Because I’m interested in category theory, I start by creating a tree entitled Category with taxon Definition. I start doing the same for other important notions, like functors, natral transformations, etc. Eventually I prove the Yoneda lemma! I spend about a year building up a glorious forest full of category theory. Only then do I realise that ordinary category theory, in which a category is defined to have a set (or a class) of objects, is a mess; I want to switch to univalent category theory which smooths over many of the rough edges. Unfortunately, univalent foundations is very different from set theoretic foundations in subtle ways. I have a plan to refactor my entire forest to account for this, but obviously I have to get my actual work done too. I’ll just hold off on that epic refactoring... I discover an interesting theorem or insight, and I want to write it down in my forest. But my motivation dies when I realise that it would mean adding to the old-and-busted notes, which would increase my future burden when I will definitely (not kidding) update my hundreds of notes. With my motivation killed, I forget about the insight and move on. By the way, not only do I want to switch to univalent categories, I also want to re-do everything in terms of displayed categories. Ouch. This happens enough times, and the forest dies and becomes a junkyard. The End. I suspect this is a somewhat common negative experience with Zettelkästen, but not many people talk about it. In one brave exception, Christian Tietze writes about a similar experience recently with his Zettelkasten, in which he has written a ton of now-outdated notes about subtleties of Apple’s SwiftUI and Observation frameworks. Keeping such things “evergreen” is almost impossible because Apple frameworks are a rapidly moving target. The point I want to make is that mathematics and the sciences are also rapidly moving targets, and if your outlook on them slows its roll long enough for it to become practical to keep a sizable forest evergreen, it may indicate intellectual stagnation more than intellectual wealth. I must also point out that keeping a forest evergreen in this sense does not only amount to updating various trees periodically. One’s mathematical development over time tends to involve not only evolving definitions and proofs, but also an evolution of the entire ontology—which means that the very decision of what to put in one tree and what to put in another tree is difficult to commit to in the long term. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXU/ QHXU /QHXU/ Tree-rings and the dialectics of knowledge production My own experience with the long-term maintenance of a forest or Zettelkasten is that the level of activity therein is uneven over time—there are periods of expansion followed by periods of quiet. In the former, trees tend to cluster around not only a group of related topics but also a particular approach to ontologising those topics. When you encounter one of those trees later on, you can kind of remember when it was written because of the way it was written and the particular relationships you chose to reify in hypertext. Seeing these distinct “rings of growth” emerging in my own forest brought me to the realisation that my viewpoint on evergreen notes might have been overly simplistic. The question seems to be: should we resist the distinctness of intellectual growth rings by hewing to a homogeneity of the present, or should we embrace time and change as fundamental aspects of knowledge production? Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXV/ QHXV /QHXV/ Resist ontology and embrace time Coming back to the difficulty of maintaining a forest in a state of intellectual evolution, I have found that a good approach is to organise my notes around “tracker” trees—which pertain to a particular topic or project but have little content of their own, serving mainly as backlink accumulators for notes written in my private journal, my weeknotes, and my blog. For example, one thing I am working on is Project Pterosaur—which will be a new proof assistant that combines dependent type theory with ideas from Isabelle/HOL. As you can see, there is very little content to the Project Pterosaur tree, but in the private version of my forest there are many backlinks coming from journal entries. I can reconstruct the entire project in my mind by reading through these entries via the backlinks panel, and that to me is far more useful than a (high-churn) “evergreen” note that explains my vision for the project and its status, etc. Obviously this is not a new idea—many people use tools like Obsidian, Logseq, Roam, etc. in the way I am describing. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXX/ QHXX /QHXX/ Blogging is the accretion of temporal insight A few months ago, I had a very enlightening conversation with my colleague Anil Madhavapeddy about blogging. Anil’s research group at Cambridge has a practice of internal blogging and weeknotes: pretty much everyone is writing about their work in blogs that are then syndicated into a Matrix channel. Then, discussion proceeds organically in the chat and in person. These blog posts are not the transient/fleeting notes discussed by Matuschak, because they are not scraps—they are evergreen in the “free” sense of being permanent discourses on a moment in time. For more than a year, I had already been maintaining a personal journal of daily notes in my private forest, but there was always some tension in my writing practices there because I was perfunctorily accumulating “records” of what I did rather than insight. What had not clicked for me at the time was that I really ought to have been blogging (for myself). Journalling in the most progressive sense is simply blogging with a restricted audience, facilitating the accretion of insight more than the mere memory of what happened when. Since my chat with Anil, I have shifted my practice to emphasise semi-public weeknotes whose goal is to provoke and continue discussions that are unfolding within the community that reads them (mainly my colleagues in the Computer Laboratory). Of course, this was only possible after I had added support for syndication to Forester! I still write private entries as well, of course, but not as many. Currently, Forester creates a lot of friction around access control and one of the goals in the coming year or two is to decrease this friction so that one does not have to think so carefully about where to put something that you want to write. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXW/ QHXW /QHXW/ Sprouting shoots, and the Hyperbook I have written above about a forestry practice that embeds time and the evolution of ideas at its core; this is achieved by resisting the packrat’s urge to ontologise every aspect of their intellectual life. This does not mean that static ontologisation has no place; for example, a textbook should not present an evolution of its own ideas (except insofar as it describes history), but should rather present a single unified viewpoint on a topic. Indeed, the original goal of Forester was to simplify the creation and deployment of resources like the Stacks Project and Kerodon, which I will hereafter refer to as hyperbooks. In the hyperbook, we can and must give full play to our instinct for ontologisation, and we are freed from the crushing obligation of permanence by treating a hyperbook in the same way that we treat a blog post: as a unified accretion of insight that pertains to a specific moment in time, making no pretensions as to the universality of the specific ontological approach. This should not surprise anyone who has written books or lecture notes before, but it does represent a retreat from what might now be viewed as an “extremist deviation” in the design of Forester. Prior to Forester 5.0, each person was expected to have just a single forest and all their writings (including lecture notes and hyperbooks!) were expected to be part of that forest. I found that this approach, however, intensifies all the kinds of metal stress that kills motivation and hastens descent into the intellectual junkyard. A better way forward is to liberally split off hyperbooks as independent forests—which can then be federated with your own forest (please note that this functionality is experimental and subject to change). The ability to federate forests is important, because otherwise one would have to choose between bidirectional linking and modularity; with federation, there is no need to make this choice. Splitting off forests in Forester 5.0 still involves some annoying points of friction; the biggest one is the need for global identity that spans all forests. A solution to this problem will not ship with 5.0, but I am preparing to work on it for a subsequent release. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXY/ QHXY /QHXY/ Renew life, have a forest fire! The goal of the Forester project has always been to reduce mental stress and release untapped stores of creativity in the struggle for outlook and insight. In some sense, every iteration of Forester has been an experiment from which we are taking both positive and negative lessons. Some users of Forester have adopted extreme ontological practices (abetted, perhaps regrettably, by our dangerously powerful Datalog query engine). It is not my place to prescribe how people should use Forester, but I do care for people’s well-being and I strongly believe that these kinds of practices can destroy the mind over time. If you are feeling the weight of ontology in a heavy-laden forest, there is nothing wrong with a little forest fire. When the smoke clears, start a blog. Jon Sterling 2023 5 14 2024 4 25 2025 5 26 https://www.forester-notes.org/0052/ 0052 /0052/ Build your own Stacks Project in 10 minutes The Stacks project is the most successful scientific hypertext project in history. Its goal is to lay the foundations for the theory of algebraic stacks; to facilitate its scalable and sustainable development, several important innovations have been introduced, with the tags system being the most striking. Each tag refers to a unique item (section, lemma, theorem, etc.) in order for this project to be referenceable. These tags don't change even if the item moves within the text. (Tags explained, The Stacks Project). Many working scientists, students, and hobbyists have wished to create their own tag-based hypertext knowledge base, but the combination of tools historically required to make this happen are extremely daunting. Both the Stacks project and Kerodon use a cluster of software called Gerby, but bitrot has set in and it is no longer possible to build its dependencies on a modern environment without significant difficulty, raising questions of longevity. Moreover, Gerby’s deployment involves running a database on a server (in spite of the fact that almost the entire functionality is static HTML), an architecture that is incompatible with the constraints of the everyday working scientist or student who knows at most how to upload static files to their university-provided public storage. The recent experience of the nLab’s pandemic-era hiatus and near death experience has demonstrated with some urgency the pracarity faced by any project relying heavily on volunteer system administrators. Jon Sterling 2023 5 14 https://www.forester-notes.org/0053/ 0053 /0053/ Introducing Forester: a tool for scientific thought After spending two years exploring the design of tools for scientific thought that meet the unique needs of real, scalable scientific writing in hypertext, I have created a tool called Forester which has the following benefits: Forester is tag-based like Gerby, and can therefore power large-scale generational projects like Stacks and Kerodon. Forester produces static content that can be uploaded to any web hosting service without needing to run or install any serverside software. Forester is easy to install on your own machine. To prevent bitrot, Forester is a single tool rather than a composition of several tools. Forester satisfies all the requirements of serious scientific writing, including sophisticated notational macros, typesetting of diagrams, etc. Forester combines associative and hierarchical networks of evergreen notes (called “trees”) into hypertext sites called “forests”. Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000R/ tfmt-000R /tfmt-000R/ Forests and trees of evergreen notes Definition A forest of evergreen notes (or a forest for short) is loosely defined to be a collection of evergreen notes in which multiple hierarchical structures are allowed to emerge and evolve over time. Concretely, one note may contextualize several other notes via transclusion within its textual structure; in the context of a forest, we refer to an individual note as a tree. Of course, a tree can be viewed as a forest that has a root node. Trees correspond roughly to what are referred to as “tags” in the Stacks Project. In this article, I will show you how to set up your own forest using the Forester software. These instructions pertain to the Forester 5.0 version. Jon Sterling 2023 8 13 https://www.forester-notes.org/006R/ 006R /006R/ Preparing to run the Forester software In this section, we will walk through the installation of the Forester software. Jon Sterling 2023 8 13 https://www.forester-notes.org/006S/ 006S /006S/ System requirements of Forester Jon Sterling 2023 8 13 https://www.forester-notes.org/006T/ 006T /006T/ A unix-based system Requirement Forester requires a unix-based system to run; it has been tested on both macOS and Linux. Windows support is desirable, but there are no concrete plans to implement it at this time. Jon Sterling 2023 8 13 https://www.forester-notes.org/006U/ 006U /006U/ A working OCaml 5 installation Requirement Forester is written in the OCaml programming language, and makes use of the latest features of OCaml 5. Most users should install Forester through OCaml's opam package manager; instructions to install opam and OCaml simultaneously can be found here. Jon Sterling 2023 8 13 https://www.forester-notes.org/006V/ 006V /006V/ A working installation Requirement If you intend to embed -rendered diagrams in your forest, you will need to have a working installation of installed, such as TeX Live. If all your mathematical expressions are supported by , this is not necessary. Jon Sterling 2023 8 14 https://www.forester-notes.org/006Y/ 006Y /006Y/ The git distributed version control system Requirement It is best practice to maintain your forest inside of distributed version control. This serves not only as a way to prevent data loss (because you will be pushing frequently to a remote repository); it also allows you to easily roll back to an earlier version of your forest, or to create “branches” in which you prepare trees that are not yet ready to be integrated into the forest. The recommended distributed version control system is git, which comes preinstalled on many unix-based systems and is easy to install otherwise. Git is not the most user-friendly piece of software, unfortunately, but it is ubiquitous. It is possible (but not recommended) to use Forester without version control, but note that the simplest way to initialize your own forest involves cloning a git repository. Jon Sterling 2023 8 13 https://www.forester-notes.org/006W/ 006W /006W/ Installing the Forester software Once you have met the system requirements, installing Forester requires only a single shell command: To verify that Forester is installed, please run forester --version in your shell. Jon Sterling 2023 8 14 2024 4 25 2024 6 17 https://www.forester-notes.org/006X/ 006X /006X/ Setting up your forest from the template Now that you have installed the Forester software, it is time to set up your forest. Forester provides a simple command to initialise a fresh forest within a folder. We’ll call our folder forest, but you can call it anything you want. Now that we are inside our new directory, we can instruct Forester to initialise a forest. forester init This command initialises a git repository with the skeleton of a forest, which contains a configuration file named forest.toml; this file specifies the locations of your trees, assets, etc. There is also a git submodule bound to the theme/ directory (pointing to the base theme repository) that contains the stylesheets that web browsers will need in order to render your forest as HTML. Jon Sterling 2023 8 14 2024 6 17 https://www.forester-notes.org/0073/ 0073 /0073/ Tree addresses in a forest A tree in Forester is usually associated to an address of the form NNNN is a four-digit base-36 number. The purpose of the base-36 code is to uniquely identify a tree within your forest in such a way that you are not tempted to rename it, as you might be when titles or dates are embedded into filenames. A tree with address NNNN is stored in a file named NNNN.tree (unless it is emitted from inside another tree by means of the inline subtrees feature). Note that the format of tree addresses is purely a matter of convention, and is not forced by the Forester tool. Users are free to use their own naming convention for tree addresses, and in some cases alternative (human-readable) formats may be desirable: this includes trees representing bibliographic references, as well as biographical trees. If you don’t like numerical tree addresses, nobody is forcing you to use them. The use of numerical addresses is suitable for projects like The Stacks Project, but it may not be appropriate for your own use-case. Addresses in Forester are not hierarchical: all resources are rendered at the root of the forest, no matter where their source files are kept. This limitation is intentional, but we might revisit it in the future. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007D/ 007D /007D/ Building and viewing your forest for the first time To build your forest, you can run the following command of Forester's executable in your shell: forester build forest.toml The --dev flag is optional, and when activated supplies metadata to the generated website to support an “edit button” on each tree; this flag is meant to be used when developing your forest locally, and should not be used when building the forest to be uploaded to your public web host. Jon Sterling 2023 8 15 https://www.forester-notes.org/007G/ 007G /007G/ Forester renders each tree to an XML document Forester renders your forest to some XML files in the output/ directory; XML is, like HTML, a format for structured documents that can be displayed by web browsers. The forest template comes equipped with a built-in XSLT stylesheet (theme/default.xsl) which is used to instruct web browsers how to render your forest into a pleasing and readable format. Jon Sterling 2023 8 15 https://www.forester-notes.org/007I/ 007I /007I/ Serving and viewing your forest from a local web server To view your forest while editing it, you must serve it from a local web server..To do this, first ensure that you have Python 3 correctly installed. Then run the following command from the root directory of your forest: python3 -m http.server 1313 -d output (You could replace 1313 with whatever port you prefer.) While this command is running, you will be able to access your forest by navigating to localhost:1313 in your preferred web browser. In the future, Forester may be able to run its own local server to avoid the dependency on external tools like Python. Jon Sterling 2023 8 15 https://www.forester-notes.org/007K/ 007K /007K/ Creating your personal biographical tree The first tree that you should create is a biographical tree to represent your own identity; ultimately you will link to this tree when you set the authors of other trees that you create later on. It is convenient to simply use a person’s full name to address a biographical tree. My own biographical tree is located at trees/people/jonmsterling.tree and contains the following source code: Let’s break this code down to understand what it does. The declaration sets the title of the tree to my name. The declaration informs Forester that the tree is biographical. Not ever tree needs to have a taxon; common taxa include Person, Theorem, Definition, Lemma, etc. You are free to use whatever you want, but some taxa are treated specially by Forester. The subsequent declarations attach additional information to the tree that can be used during rendering. These declarations are optional, and you are free to put whatever metadata you want. Like in HTML, paragraphs must be wrapped in . Do not hard-wrap your text, as this can have visible impact on how trees are rendered; it is recommended that you use a text editor with good support for soft-wrapping, like Visual Studio Code. You can see that the concrete syntax of Forester's trees looks superficially like a combination of and Markdown; Markdown-style links are used both for links to other trees and for links to external URLs. Forester's concrete syntax is not fully documented, but it is less ambiguous than both and Markdown. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007H/ 007H /007H/ Creating a new tree using forester new Creating a new tree in your forest is as simple as adding a .tree file to the trees folder. Because it is hard to manually choose the next incremental tree address, Forester provides a command to do this automatically: forester new forest.toml --dest=trees In return, Forester should output the location of the new tree, e.g. trees/0002.tree. If we look at the contents of this new file, we will see that it is empty except for metadata assigning a date to the tree: You may prefer to use randomised addresses over sequential addresses; this can be particularly useful if multiple people are contributing to a forest. In that case, pass the --random option to forester new. Most trees should have a annotation; this date is meant to be the date of the tree's creation; you can have more than one date, if you like to keep track of when a tree has been updated. You should proceed by adding further metadata: the title and the author; for the latter, you will use the address of your personal biographical tree. Tree titles should be given in lower case (except for proper names, etc.); these titles will be rendered by Forester in sentence case. A tree can have as many declarations as it has authors; these will be rendered in their order of appearance. Now you can begin to populate the tree with its content, written in the Forester markup language. Think carefully about keeping each tree relatively independent and atomic. Jon Sterling 2023 8 15 https://www.forester-notes.org/007L/ 007L /007L/ Bottom-up hierarchy via transclusion You may be used to writing documents, where you work from the top down: you create some section headings, put some text under those headings, make some deeper section headings, put more text, etc. Forests work in the opposite way, from the bottom up: you start by writing independent, atomic notes/trees and then only later start to (sparingly) assemble these into a hierarchy in order to reify the emerging structure. Forester’s bottom-up approach to section hierarchy works via something called transclusion. The idea is that at any time, you can include (“transclude”) the full contents of another tree into the current tree as a subsection by adding the following code: This is kind of like ’s command, but much better behaved: for instance, section levels are computed on the fly depending on the position in the hierarchy. This entire tutorial is cobbled together by transcluding many smaller trees, each with their own independent existence. For example, the following two sections are transcluded from an entirely different part of my forest: Jon Sterling 2022 12 27 https://www.forester-notes.org/tfmt-0009/ tfmt-0009 /tfmt-0009/ The best structure to impose is relatively flat It is easy to make the mistake of prematurely imposing a complex hierarchical structure on a network of notes, which leads to excessive refactoring. Hierarchy should be used sparingly, and its strength is for the large-scale organization of ideas. The best structure to impose on a network of many small related ideas is a relatively flat one. I believe that this is one of the mistakes made in the writing of the foundations of relative category theory, whose hierarchical nesting was too complex and quite beholden to my experience with pre-hypertext media. One of the immediate impacts and strengths of Forester’s transclusion model is that a given tree has no canonical “geographic” location in the forest. One tree can appear as a child of many other trees, which allows the same content to be incorporated into different textual and intellectual narratives. Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0006/ tfmt-0006 /tfmt-0006/ Hierarchical structure as non-unique narrative Multiple hierarchical structures can be imposed on the same associative network of nodes; a hierarchical structure amounts to a “narrative” that contextualizes a given subgraph of the network. One example could be the construction of lecture notes; another example could be a homework sheet; a further example could be a book chapter or scientific article. Although these may draw from the same body of definitions, theorems, examples, and exercises, these objects are contextualized within a different narrative, often toward fundamentally different ends. As a result, any interface for navigating the neighbor-relation in hierarchically organized notes would need to take account of the multiplicity of parent nodes. Most hypertext tools assume that the position of a node in the hierarchy is unique, and therefore have a single “next/previous” navigation interface; we must investigate the design of interfaces that surface all parent/neighbor relations. Jon Sterling 2023 8 16 https://www.forester-notes.org/007N/ 007N /007N/ The Forester markup language A tree in Forester is a single file written in a markup language designed specifically for scientific writing with bottom-up hierarchy via transclusion. A tree has two components: the frontmatter and the mainmatter. Jon Sterling 2023 8 16 https://www.forester-notes.org/007P/ 007P /007P/ Forester markup: frontmatter The frontmatter of a Forester tree is a sequence of declarations that we summarize below. Declaration Meaning sets the title of the tree; can contain mainmatter markup sets the author of the tree to be the biographical tree at address name sets the creation date of the tree; full ISO 8601 date-times are supported. sets the taxon of the tree; example taxa include lemma, theorem, person, reference; the latter two taxa are treated specially by Forester for tracking biographical and bibliographical trees respectively defines and exports from the current tree a function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for brings the functions exported by the tree address into scope brings the functions exported by the tree address into scope, and exports them from the current tree Jon Sterling 2023 8 16 https://www.forester-notes.org/007O/ 007O /007O/ Forester markup: mainmatter Below we summarize the concrete syntax of the mainmatter in a Forester tree. Function Meaning creates a paragraph containing ...; unlike Markdown, it is mandatory to annotate paragraphs explicitly typesets the content in italics typesets the content in boldface creates an ordered list creates an unordered list creates a list item typesets the content in (inline) math mode using ; note that math mode is idempotent in Forester typesets the content in (display) math mode using transcludes the tree at address address as a subsection formats the text title as a hyperlink to address address; if address is the address of a tree, the link will point to that tree, and otherwise it is treated as a URL defines a local function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for . typesets the content in monospace typesets the body externally using using preamble as preamble code (e.g. to set up tikz packages, etc.). It can be useful to wrap this in your own macro in order to insert your preamble code automatically. Jon Sterling 2023 8 16 https://www.forester-notes.org/007Q/ 007Q /007Q/ An complete worked example tree in Forester Example An example of a complete tree in the Forester markup language can be seen below. The code above results in the following tree: Jon Sterling 2023 2 11 https://www.forester-notes.org/001H/ 001H /001H/ Creation of (co)limits Definition Let be a functor and let be a category. The functor is said to create (co)limits of -figures when for any diagram such that has a (co)limit, then has a (co)limit that is both preserved and reflected by . Jon Sterling 2023 8 16 https://www.forester-notes.org/007R/ 007R /007R/ Deploying your forest to a web host Now that you have created your forest and added a few trees of your own, it is time to upload it to your web host. Many users of Forester will have university-supplied static web hosting, and others may prefer to use GitHub pages; deploying a forest works the same way in either case. First, make sure your forest is built using the earlier instructions. Then take the entire contents of your output directory and upload them to your preferred web host. Jon Sterling 2023 8 16 https://www.forester-notes.org/007S/ 007S /007S/ Let a hundred forests bloom! I am eager to see the new forests that people create using Forester. I am happy to offer personal assistance via the mailing list. Many aspects of Forester are in flux and not fully documented; it will often be instructive to consult the source of existings forests, such as this one. Have fun, and be sure to send me links to your forests when you have made them! Kento Okura Jon Sterling 2025 3 28 https://www.forester-notes.org/MZSF/ MZSF /MZSF/ The Forester language server Forester provides an implementation of the Language Server Protocol (LSP). Developers of editor plugins can consult forester lsp --help. Jon Sterling Kento Okura 2025 5 26 https://www.forester-notes.org/24B1/ 24B1 /24B1/ Features of the Forester language server Forester’s implementation of the language server protocol supports several standard features to varying degrees. At the moment we support some code actions (e.g. creating a new tree), inlay hints, syntax error diagnostics, document symbols, workspace symbols, and link completion. There may be limitations in the implementations of these features, which we will continue to improve; we appreciate user feedback. (Please note that LSP features are surfaced differently in every editor (language server client); although we provide a sample configuration for Neovim, for example, not all features of the LSP have been surfaced to the user in that configuration.) Kento Okura Jon Sterling https://www.forester-notes.org/QLG4/ QLG4 /QLG4/ Example configurations Users of other text editors are encouraged to contribute to this section. https://www.forester-notes.org/LN6D/ LN6D /LN6D/ Neovim configuration Since Neovim version 0.11, you can configure language servers by simply adding the following snippet to your configuration: For a more complete configuration that includes keybinds to various features, you can use this template as a starting point. If you are not yet using version 0.11, please refer to the documentation of nvim-lspconfig Kento Okura Jon Sterling https://www.forester-notes.org/6Y7J/ 6Y7J /6Y7J/ Helix configuration You must add the following to languages.toml in your Helix configuration directory, following the documentation. Kento Okura 2025 3 28 Known issues While the language server does not yet support semantic syntax highlighting, you may try to use tree-sitter-forester, although it is currently not officially supported Neovim does not handle WorkspaceEdit notifications. This means that after creating a new tree via a code action, the language server will become out of sync. VSCode issue Inlay hints do not properly refresh upon changes. Toggling the feature on and off seems to resolve this in Neovim The server will not be aware of any trees or assets added in file system after startup. Jon Sterling 2023 8 14 2024 4 25 2024 6 17 https://www.forester-notes.org/006X/ 006X /006X/ Setting up your forest from the template Now that you have installed the Forester software, it is time to set up your forest. Forester provides a simple command to initialise a fresh forest within a folder. We’ll call our folder forest, but you can call it anything you want. Now that we are inside our new directory, we can instruct Forester to initialise a forest. forester init This command initialises a git repository with the skeleton of a forest, which contains a configuration file named forest.toml; this file specifies the locations of your trees, assets, etc. There is also a git submodule bound to the theme/ directory (pointing to the base theme repository) that contains the stylesheets that web browsers will need in order to render your forest as HTML. Jon Sterling 2023 8 14 2024 6 17 https://www.forester-notes.org/0073/ 0073 /0073/ Tree addresses in a forest A tree in Forester is usually associated to an address of the form NNNN is a four-digit base-36 number. The purpose of the base-36 code is to uniquely identify a tree within your forest in such a way that you are not tempted to rename it, as you might be when titles or dates are embedded into filenames. A tree with address NNNN is stored in a file named NNNN.tree (unless it is emitted from inside another tree by means of the inline subtrees feature). Note that the format of tree addresses is purely a matter of convention, and is not forced by the Forester tool. Users are free to use their own naming convention for tree addresses, and in some cases alternative (human-readable) formats may be desirable: this includes trees representing bibliographic references, as well as biographical trees. If you don’t like numerical tree addresses, nobody is forcing you to use them. The use of numerical addresses is suitable for projects like The Stacks Project, but it may not be appropriate for your own use-case. Addresses in Forester are not hierarchical: all resources are rendered at the root of the forest, no matter where their source files are kept. This limitation is intentional, but we might revisit it in the future. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007D/ 007D /007D/ Building and viewing your forest for the first time To build your forest, you can run the following command of Forester's executable in your shell: forester build forest.toml The --dev flag is optional, and when activated supplies metadata to the generated website to support an “edit button” on each tree; this flag is meant to be used when developing your forest locally, and should not be used when building the forest to be uploaded to your public web host. Jon Sterling 2023 8 15 https://www.forester-notes.org/007G/ 007G /007G/ Forester renders each tree to an XML document Forester renders your forest to some XML files in the output/ directory; XML is, like HTML, a format for structured documents that can be displayed by web browsers. The forest template comes equipped with a built-in XSLT stylesheet (theme/default.xsl) which is used to instruct web browsers how to render your forest into a pleasing and readable format. Jon Sterling 2023 8 15 https://www.forester-notes.org/007I/ 007I /007I/ Serving and viewing your forest from a local web server To view your forest while editing it, you must serve it from a local web server..To do this, first ensure that you have Python 3 correctly installed. Then run the following command from the root directory of your forest: python3 -m http.server 1313 -d output (You could replace 1313 with whatever port you prefer.) While this command is running, you will be able to access your forest by navigating to localhost:1313 in your preferred web browser. In the future, Forester may be able to run its own local server to avoid the dependency on external tools like Python. Jon Sterling 2023 8 14 2024 6 17 https://www.forester-notes.org/0073/ 0073 /0073/ Tree addresses in a forest A tree in Forester is usually associated to an address of the form NNNN is a four-digit base-36 number. The purpose of the base-36 code is to uniquely identify a tree within your forest in such a way that you are not tempted to rename it, as you might be when titles or dates are embedded into filenames. A tree with address NNNN is stored in a file named NNNN.tree (unless it is emitted from inside another tree by means of the inline subtrees feature). Note that the format of tree addresses is purely a matter of convention, and is not forced by the Forester tool. Users are free to use their own naming convention for tree addresses, and in some cases alternative (human-readable) formats may be desirable: this includes trees representing bibliographic references, as well as biographical trees. If you don’t like numerical tree addresses, nobody is forcing you to use them. The use of numerical addresses is suitable for projects like The Stacks Project, but it may not be appropriate for your own use-case. Addresses in Forester are not hierarchical: all resources are rendered at the root of the forest, no matter where their source files are kept. This limitation is intentional, but we might revisit it in the future. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007D/ 007D /007D/ Building and viewing your forest for the first time To build your forest, you can run the following command of Forester's executable in your shell: forester build forest.toml The --dev flag is optional, and when activated supplies metadata to the generated website to support an “edit button” on each tree; this flag is meant to be used when developing your forest locally, and should not be used when building the forest to be uploaded to your public web host. Jon Sterling 2023 8 15 https://www.forester-notes.org/007G/ 007G /007G/ Forester renders each tree to an XML document Forester renders your forest to some XML files in the output/ directory; XML is, like HTML, a format for structured documents that can be displayed by web browsers. The forest template comes equipped with a built-in XSLT stylesheet (theme/default.xsl) which is used to instruct web browsers how to render your forest into a pleasing and readable format. Jon Sterling 2023 8 15 https://www.forester-notes.org/007I/ 007I /007I/ Serving and viewing your forest from a local web server To view your forest while editing it, you must serve it from a local web server..To do this, first ensure that you have Python 3 correctly installed. Then run the following command from the root directory of your forest: python3 -m http.server 1313 -d output (You could replace 1313 with whatever port you prefer.) While this command is running, you will be able to access your forest by navigating to localhost:1313 in your preferred web browser. In the future, Forester may be able to run its own local server to avoid the dependency on external tools like Python. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007H/ 007H /007H/ Creating a new tree using forester new Creating a new tree in your forest is as simple as adding a .tree file to the trees folder. Because it is hard to manually choose the next incremental tree address, Forester provides a command to do this automatically: forester new forest.toml --dest=trees In return, Forester should output the location of the new tree, e.g. trees/0002.tree. If we look at the contents of this new file, we will see that it is empty except for metadata assigning a date to the tree: You may prefer to use randomised addresses over sequential addresses; this can be particularly useful if multiple people are contributing to a forest. In that case, pass the --random option to forester new. Most trees should have a annotation; this date is meant to be the date of the tree's creation; you can have more than one date, if you like to keep track of when a tree has been updated. You should proceed by adding further metadata: the title and the author; for the latter, you will use the address of your personal biographical tree. Tree titles should be given in lower case (except for proper names, etc.); these titles will be rendered by Forester in sentence case. A tree can have as many declarations as it has authors; these will be rendered in their order of appearance. Now you can begin to populate the tree with its content, written in the Forester markup language. Think carefully about keeping each tree relatively independent and atomic. Jon Sterling 2023 8 16 https://www.forester-notes.org/007Q/ 007Q /007Q/ An complete worked example tree in Forester Example An example of a complete tree in the Forester markup language can be seen below. The code above results in the following tree: Jon Sterling 2023 2 11 https://www.forester-notes.org/001H/ 001H /001H/ Creation of (co)limits Definition Let be a functor and let be a category. The functor is said to create (co)limits of -figures when for any diagram such that has a (co)limit, then has a (co)limit that is both preserved and reflected by . Jon Sterling 2023 8 16 https://www.forester-notes.org/007R/ 007R /007R/ Deploying your forest to a web host Now that you have created your forest and added a few trees of your own, it is time to upload it to your web host. Many users of Forester will have university-supplied static web hosting, and others may prefer to use GitHub pages; deploying a forest works the same way in either case. First, make sure your forest is built using the earlier instructions. Then take the entire contents of your output directory and upload them to your preferred web host. Jon Sterling 2023 8 16 https://www.forester-notes.org/007P/ 007P /007P/ Forester markup: frontmatter The frontmatter of a Forester tree is a sequence of declarations that we summarize below. Declaration Meaning sets the title of the tree; can contain mainmatter markup sets the author of the tree to be the biographical tree at address name sets the creation date of the tree; full ISO 8601 date-times are supported. sets the taxon of the tree; example taxa include lemma, theorem, person, reference; the latter two taxa are treated specially by Forester for tracking biographical and bibliographical trees respectively defines and exports from the current tree a function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for brings the functions exported by the tree address into scope brings the functions exported by the tree address into scope, and exports them from the current tree Jon Sterling 2023 8 16 https://www.forester-notes.org/007O/ 007O /007O/ Forester markup: mainmatter Below we summarize the concrete syntax of the mainmatter in a Forester tree. Function Meaning creates a paragraph containing ...; unlike Markdown, it is mandatory to annotate paragraphs explicitly typesets the content in italics typesets the content in boldface creates an ordered list creates an unordered list creates a list item typesets the content in (inline) math mode using ; note that math mode is idempotent in Forester typesets the content in (display) math mode using transcludes the tree at address address as a subsection formats the text title as a hyperlink to address address; if address is the address of a tree, the link will point to that tree, and otherwise it is treated as a URL defines a local function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for . typesets the content in monospace typesets the body externally using using preamble as preamble code (e.g. to set up tikz packages, etc.). It can be useful to wrap this in your own macro in order to insert your preamble code automatically. Jon Sterling 2023 8 16 https://www.forester-notes.org/007S/ 007S /007S/ Let a hundred forests bloom! I am eager to see the new forests that people create using Forester. I am happy to offer personal assistance via the mailing list. Many aspects of Forester are in flux and not fully documented; it will often be instructive to consult the source of existings forests, such as this one. Have fun, and be sure to send me links to your forests when you have made them! Jon Sterling 2023 8 16 https://www.forester-notes.org/007N/ 007N /007N/ The Forester markup language A tree in Forester is a single file written in a markup language designed specifically for scientific writing with bottom-up hierarchy via transclusion. A tree has two components: the frontmatter and the mainmatter. Jon Sterling 2023 8 16 https://www.forester-notes.org/007P/ 007P /007P/ Forester markup: frontmatter The frontmatter of a Forester tree is a sequence of declarations that we summarize below. Declaration Meaning sets the title of the tree; can contain mainmatter markup sets the author of the tree to be the biographical tree at address name sets the creation date of the tree; full ISO 8601 date-times are supported. sets the taxon of the tree; example taxa include lemma, theorem, person, reference; the latter two taxa are treated specially by Forester for tracking biographical and bibliographical trees respectively defines and exports from the current tree a function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for brings the functions exported by the tree address into scope brings the functions exported by the tree address into scope, and exports them from the current tree Jon Sterling 2023 8 16 https://www.forester-notes.org/007O/ 007O /007O/ Forester markup: mainmatter Below we summarize the concrete syntax of the mainmatter in a Forester tree. Function Meaning creates a paragraph containing ...; unlike Markdown, it is mandatory to annotate paragraphs explicitly typesets the content in italics typesets the content in boldface creates an ordered list creates an unordered list creates a list item typesets the content in (inline) math mode using ; note that math mode is idempotent in Forester typesets the content in (display) math mode using transcludes the tree at address address as a subsection formats the text title as a hyperlink to address address; if address is the address of a tree, the link will point to that tree, and otherwise it is treated as a URL defines a local function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for . typesets the content in monospace typesets the body externally using using preamble as preamble code (e.g. to set up tikz packages, etc.). It can be useful to wrap this in your own macro in order to insert your preamble code automatically. Jon Sterling 2023 8 16 https://www.forester-notes.org/007Q/ 007Q /007Q/ An complete worked example tree in Forester Example An example of a complete tree in the Forester markup language can be seen below. The code above results in the following tree: Jon Sterling 2023 2 11 https://www.forester-notes.org/001H/ 001H /001H/ Creation of (co)limits Definition Let be a functor and let be a category. The functor is said to create (co)limits of -figures when for any diagram such that has a (co)limit, then has a (co)limit that is both preserved and reflected by . Jon Sterling 2023 8 15 https://www.forester-notes.org/007L/ 007L /007L/ Bottom-up hierarchy via transclusion You may be used to writing documents, where you work from the top down: you create some section headings, put some text under those headings, make some deeper section headings, put more text, etc. Forests work in the opposite way, from the bottom up: you start by writing independent, atomic notes/trees and then only later start to (sparingly) assemble these into a hierarchy in order to reify the emerging structure. Forester’s bottom-up approach to section hierarchy works via something called transclusion. The idea is that at any time, you can include (“transclude”) the full contents of another tree into the current tree as a subsection by adding the following code: This is kind of like ’s command, but much better behaved: for instance, section levels are computed on the fly depending on the position in the hierarchy. This entire tutorial is cobbled together by transcluding many smaller trees, each with their own independent existence. For example, the following two sections are transcluded from an entirely different part of my forest: Jon Sterling 2022 12 27 https://www.forester-notes.org/tfmt-0009/ tfmt-0009 /tfmt-0009/ The best structure to impose is relatively flat It is easy to make the mistake of prematurely imposing a complex hierarchical structure on a network of notes, which leads to excessive refactoring. Hierarchy should be used sparingly, and its strength is for the large-scale organization of ideas. The best structure to impose on a network of many small related ideas is a relatively flat one. I believe that this is one of the mistakes made in the writing of the foundations of relative category theory, whose hierarchical nesting was too complex and quite beholden to my experience with pre-hypertext media. One of the immediate impacts and strengths of Forester’s transclusion model is that a given tree has no canonical “geographic” location in the forest. One tree can appear as a child of many other trees, which allows the same content to be incorporated into different textual and intellectual narratives. Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0006/ tfmt-0006 /tfmt-0006/ Hierarchical structure as non-unique narrative Multiple hierarchical structures can be imposed on the same associative network of nodes; a hierarchical structure amounts to a “narrative” that contextualizes a given subgraph of the network. One example could be the construction of lecture notes; another example could be a homework sheet; a further example could be a book chapter or scientific article. Although these may draw from the same body of definitions, theorems, examples, and exercises, these objects are contextualized within a different narrative, often toward fundamentally different ends. As a result, any interface for navigating the neighbor-relation in hierarchically organized notes would need to take account of the multiplicity of parent nodes. Most hypertext tools assume that the position of a node in the hierarchy is unique, and therefore have a single “next/previous” navigation interface; we must investigate the design of interfaces that surface all parent/neighbor relations. Jon Sterling 2023 8 15 https://www.forester-notes.org/007K/ 007K /007K/ Creating your personal biographical tree The first tree that you should create is a biographical tree to represent your own identity; ultimately you will link to this tree when you set the authors of other trees that you create later on. It is convenient to simply use a person’s full name to address a biographical tree. My own biographical tree is located at trees/people/jonmsterling.tree and contains the following source code: Let’s break this code down to understand what it does. The declaration sets the title of the tree to my name. The declaration informs Forester that the tree is biographical. Not ever tree needs to have a taxon; common taxa include Person, Theorem, Definition, Lemma, etc. You are free to use whatever you want, but some taxa are treated specially by Forester. The subsequent declarations attach additional information to the tree that can be used during rendering. These declarations are optional, and you are free to put whatever metadata you want. Like in HTML, paragraphs must be wrapped in . Do not hard-wrap your text, as this can have visible impact on how trees are rendered; it is recommended that you use a text editor with good support for soft-wrapping, like Visual Studio Code. You can see that the concrete syntax of Forester's trees looks superficially like a combination of and Markdown; Markdown-style links are used both for links to other trees and for links to external URLs. Forester's concrete syntax is not fully documented, but it is less ambiguous than both and Markdown. Jon Sterling 2023 8 15 https://www.forester-notes.org/007G/ 007G /007G/ Forester renders each tree to an XML document Forester renders your forest to some XML files in the output/ directory; XML is, like HTML, a format for structured documents that can be displayed by web browsers. The forest template comes equipped with a built-in XSLT stylesheet (theme/default.xsl) which is used to instruct web browsers how to render your forest into a pleasing and readable format. Jon Sterling 2023 8 15 https://www.forester-notes.org/007I/ 007I /007I/ Serving and viewing your forest from a local web server To view your forest while editing it, you must serve it from a local web server..To do this, first ensure that you have Python 3 correctly installed. Then run the following command from the root directory of your forest: python3 -m http.server 1313 -d output (You could replace 1313 with whatever port you prefer.) While this command is running, you will be able to access your forest by navigating to localhost:1313 in your preferred web browser. In the future, Forester may be able to run its own local server to avoid the dependency on external tools like Python. Jon Sterling 2023 8 14 https://www.forester-notes.org/0074/ 0074 /0074/ Base-36 identifiers in Forester Base-36 numbers are encoded in Forester using the alphabet 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ. For example, the base-10 number can be written 007I in the encoding. The purpose of using base-36 rather than a more familiar counting base is that a great many distinct numbers can be fit into a very small number of digits: in just four digits, base-36 can count to — which is far higher than the anticipated number of trees in any forest. Jon Sterling 2023 8 14 https://www.forester-notes.org/006Y/ 006Y /006Y/ The git distributed version control system Requirement It is best practice to maintain your forest inside of distributed version control. This serves not only as a way to prevent data loss (because you will be pushing frequently to a remote repository); it also allows you to easily roll back to an earlier version of your forest, or to create “branches” in which you prepare trees that are not yet ready to be integrated into the forest. The recommended distributed version control system is git, which comes preinstalled on many unix-based systems and is easy to install otherwise. Git is not the most user-friendly piece of software, unfortunately, but it is ubiquitous. It is possible (but not recommended) to use Forester without version control, but note that the simplest way to initialize your own forest involves cloning a git repository. Jon Sterling 2023 8 13 https://www.forester-notes.org/006T/ 006T /006T/ A unix-based system Requirement Forester requires a unix-based system to run; it has been tested on both macOS and Linux. Windows support is desirable, but there are no concrete plans to implement it at this time. Jon Sterling 2023 8 13 https://www.forester-notes.org/006U/ 006U /006U/ A working OCaml 5 installation Requirement Forester is written in the OCaml programming language, and makes use of the latest features of OCaml 5. Most users should install Forester through OCaml's opam package manager; instructions to install opam and OCaml simultaneously can be found here. Jon Sterling 2023 8 13 https://www.forester-notes.org/006W/ 006W /006W/ Installing the Forester software Once you have met the system requirements, installing Forester requires only a single shell command: To verify that Forester is installed, please run forester --version in your shell. Jon Sterling 2023 8 13 https://www.forester-notes.org/006R/ 006R /006R/ Preparing to run the Forester software In this section, we will walk through the installation of the Forester software. Jon Sterling 2023 8 13 https://www.forester-notes.org/006S/ 006S /006S/ System requirements of Forester Jon Sterling 2023 8 13 https://www.forester-notes.org/006T/ 006T /006T/ A unix-based system Requirement Forester requires a unix-based system to run; it has been tested on both macOS and Linux. Windows support is desirable, but there are no concrete plans to implement it at this time. Jon Sterling 2023 8 13 https://www.forester-notes.org/006U/ 006U /006U/ A working OCaml 5 installation Requirement Forester is written in the OCaml programming language, and makes use of the latest features of OCaml 5. Most users should install Forester through OCaml's opam package manager; instructions to install opam and OCaml simultaneously can be found here. Jon Sterling 2023 8 13 https://www.forester-notes.org/006V/ 006V /006V/ A working installation Requirement If you intend to embed -rendered diagrams in your forest, you will need to have a working installation of installed, such as TeX Live. If all your mathematical expressions are supported by , this is not necessary. Jon Sterling 2023 8 14 https://www.forester-notes.org/006Y/ 006Y /006Y/ The git distributed version control system Requirement It is best practice to maintain your forest inside of distributed version control. This serves not only as a way to prevent data loss (because you will be pushing frequently to a remote repository); it also allows you to easily roll back to an earlier version of your forest, or to create “branches” in which you prepare trees that are not yet ready to be integrated into the forest. The recommended distributed version control system is git, which comes preinstalled on many unix-based systems and is easy to install otherwise. Git is not the most user-friendly piece of software, unfortunately, but it is ubiquitous. It is possible (but not recommended) to use Forester without version control, but note that the simplest way to initialize your own forest involves cloning a git repository. Jon Sterling 2023 8 13 https://www.forester-notes.org/006W/ 006W /006W/ Installing the Forester software Once you have met the system requirements, installing Forester requires only a single shell command: To verify that Forester is installed, please run forester --version in your shell. Jon Sterling 2023 8 13 https://www.forester-notes.org/006S/ 006S /006S/ System requirements of Forester Jon Sterling 2023 8 13 https://www.forester-notes.org/006T/ 006T /006T/ A unix-based system Requirement Forester requires a unix-based system to run; it has been tested on both macOS and Linux. Windows support is desirable, but there are no concrete plans to implement it at this time. Jon Sterling 2023 8 13 https://www.forester-notes.org/006U/ 006U /006U/ A working OCaml 5 installation Requirement Forester is written in the OCaml programming language, and makes use of the latest features of OCaml 5. Most users should install Forester through OCaml's opam package manager; instructions to install opam and OCaml simultaneously can be found here. Jon Sterling 2023 8 13 https://www.forester-notes.org/006V/ 006V /006V/ A working installation Requirement If you intend to embed -rendered diagrams in your forest, you will need to have a working installation of installed, such as TeX Live. If all your mathematical expressions are supported by , this is not necessary. Jon Sterling 2023 8 14 https://www.forester-notes.org/006Y/ 006Y /006Y/ The git distributed version control system Requirement It is best practice to maintain your forest inside of distributed version control. This serves not only as a way to prevent data loss (because you will be pushing frequently to a remote repository); it also allows you to easily roll back to an earlier version of your forest, or to create “branches” in which you prepare trees that are not yet ready to be integrated into the forest. The recommended distributed version control system is git, which comes preinstalled on many unix-based systems and is easy to install otherwise. Git is not the most user-friendly piece of software, unfortunately, but it is ubiquitous. It is possible (but not recommended) to use Forester without version control, but note that the simplest way to initialize your own forest involves cloning a git repository. Jon Sterling 2023 5 14 https://www.forester-notes.org/0053/ 0053 /0053/ Introducing Forester: a tool for scientific thought After spending two years exploring the design of tools for scientific thought that meet the unique needs of real, scalable scientific writing in hypertext, I have created a tool called Forester which has the following benefits: Forester is tag-based like Gerby, and can therefore power large-scale generational projects like Stacks and Kerodon. Forester produces static content that can be uploaded to any web hosting service without needing to run or install any serverside software. Forester is easy to install on your own machine. To prevent bitrot, Forester is a single tool rather than a composition of several tools. Forester satisfies all the requirements of serious scientific writing, including sophisticated notational macros, typesetting of diagrams, etc. Forester combines associative and hierarchical networks of evergreen notes (called “trees”) into hypertext sites called “forests”. Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000R/ tfmt-000R /tfmt-000R/ Forests and trees of evergreen notes Definition A forest of evergreen notes (or a forest for short) is loosely defined to be a collection of evergreen notes in which multiple hierarchical structures are allowed to emerge and evolve over time. Concretely, one note may contextualize several other notes via transclusion within its textual structure; in the context of a forest, we refer to an individual note as a tree. Of course, a tree can be viewed as a forest that has a root node. Trees correspond roughly to what are referred to as “tags” in the Stacks Project. Jon Sterling 2023 1 7 https://www.forester-notes.org/tfmt-000L/ tfmt-000L /tfmt-000L/ Generating images statically using LaTeX Because of the general inadequacy of the other available tools, most authors of hypertext mathematics with diagramming needs tend to rely on the static generation of images from LaTeX code using a local LaTeX toolchain. It is not difficult to instrument pandoc with a Lua filter to render tikz code to SVG images. There are also a variety of other tools that do something similar, which tend to be employed in static site generation: antex by Paolo Brasolin is used by Krater as well as jekyll-sheafy, both via jekyll-antex. Forester by Jonathan Sterling is used by the present web site. The basic architecture of such a tool is to scan for LaTeX blocks, and then identify them by a hash of their contents. This hash is used as a filename for files, which are compiled to and thence to using the tool; the resulting file is then embedded in HTML using an ]]> tag. Alternatively, is also possible to transclude the resulting ]]> element directly, but then one must be careful to rename all identifiers in the ]]> element uniquely, as it is possible for two different ]]> elements on a single page to interfere one each other. Both antex and Forester support passing a macro library to be used when rendering. Both jekyll-sheafy and Forester set their macro libraries on a page-local basis. A serious downside of generating images from LaTeX code is the negative impact on accessibility tools. This seems only slightly mitigated by the transclusion of the ]]> element as opposed to using ]]>. Ultimately accessibility for mathematical diagrams remains an unsolved problem, and it does not seem that the existing discussion on accessibility of hypertext mathematics has much to say about this problem. Jon Sterling https://www.forester-notes.org/sterling-2024-cl-forester/ sterling-2024-cl-forester /sterling-2024-cl-forester/ Forester: networked science in hypertext Reference Computer Laboratory, University of Cambridge /bafkrmidpuo45tjd55ndfgg2ipcwgfaxby7paf6em5nw7tbfgo377gfm3re.pdf Related Kento Okura 2026 2 12 https://www.forester-notes.org/VNQA/ VNQA /VNQA/ Forester Devlog Kento Okura 2026 2 19 https://www.forester-notes.org/6QYO/ 6QYO /6QYO/ Devlog 2026-W08 Kento Okura 2026 2 19 https://www.forester-notes.org/L3OL/ L3OL /L3OL/ A setup for proper documentation Last week I wrote about shipping a default theme with forester using dune's install mechanism. I realized that I could use this to bring a great offline documentation experience to forester. Achieving this ended being a simple exercise in some basic dune features. Kento Okura 2026 2 19 https://www.forester-notes.org/JODH/ JODH /JODH/ Building the documentation I wrote some code that builds a forest and produces a JSON blob using the JSON syndication feature. Here is the relevant part: Kento Okura 2026 2 19 https://www.forester-notes.org/KVLS/ KVLS /KVLS/ Installing the documentation using dune Below is an abbreviated version of the dune file. The rule stanza tells dune to run the forester_docs executable, which builds the documentation. The deps stanza tells dune that this depends on the files contained in the trees directory. The result is this file: _build/default/bin/docs/output/docs.json. The install stanza tells dune to copy the resulting file to the installation directory, which in this case is something like $OPAM_DIR/man/docs/forest. Kento Okura 2026 2 19 https://www.forester-notes.org/UNAU/ UNAU /UNAU/ Delivering to the user Now that the documentation is installed on the user's system, we will use dune sites to implant the documentation into the users forest in dev mode. include_in_manifest = true means that the documentation is searchable using the familiar CTRL-k keybinding. In dev mode we render a link to the docs in the header: Kento Okura 2026 2 19 https://www.forester-notes.org/9UD6/ 9UD6 /9UD6/ Future steps Besides actually writing the documentation, I'd like to find a good solution for documenting Forester's features directly in the source code. An initial idea was to write a preprocessor that allows me to annotate Forester's source code with Forester syntax. Anil has kindly made me aware of Jon Ludlam's work on odoc. Having had a cursory look at what is possible makes me hopeful that we can come up with a system that easily allows us to keep the Forester's documentation up to date at all times. Kento Okura 2026 2 12 https://www.forester-notes.org/VNQC/ VNQC /VNQC/ Devlog 2026-W07 Kento Okura 2026 2 12 https://www.forester-notes.org/8FD3/ 8FD3 /8FD3/ Direct emission of HTML For reasons outlined here and here, we need to abandon XSLT for our HTML output. Apparently, we have until November 17, 2026 to achieve this! Starting with the next release, Forester will emit HTML directly. To this end, I have been reimplementing the functionality of Forester's XSL stylesheet in OCaml. We will retain emission of Forester's XML format behind a feature flag, as not to break legacy workflows. However, users will no longer be able to rely on the browser to apply the stylesheet. The XML format will also cease to receive updates, which perhaps is for the better anyway. Kento Okura 2026 2 12 https://www.forester-notes.org/EQ74/ EQ74 /EQ74/ Built-in default theme Forester's handling of themes using git submodules introduced in version 2.5 have long been a source of trouble. It made getting started more difficult. I have implemented the forester init subcommand to help with this, but I feel as though that command was too brittle for my liking. It made updating to a new version to forester troublesome, especially when heavy customization of the theme was involved. From now on, Forester will ship with a default theme. Any changes to the theme will incur a minor version bump and users will be able to update to the new version by simply running opam update forester && opam upgrade forester. This won't affect users who customize their theme, but will greatly improve the user experience for everyone else, since it is no longer required to keep a copy of the theme inside of the base directory. For users who customized their theme, the forest.theme key has been restored. Setting [forest.theme] = theme will restore the behavior of previous versions of forester. Kento Okura 2026 2 12 https://www.forester-notes.org/4QMB/ 4QMB /4QMB/ Hand-rolled ninja-keys replacement To lessen our dependency on the NPM ecosystem, I have crudely reimplemented ninja-keys using Js_of_ocaml and the excellent BRR toolkit by Daniel Bünzli. I have not yet achieved feature parity, and there is lots of room for improvement. I am looking forward to hacking around in this area. Any suggestions or feature requests for the new search menu are most welcome! Jon Sterling 2024 11 27 https://www.forester-notes.org/5CDY/ 5CDY /5CDY/ Presentations Jon Sterling https://www.forester-notes.org/sterling-2024-cl-forester/ sterling-2024-cl-forester /sterling-2024-cl-forester/ Forester: networked science in hypertext Reference Computer Laboratory, University of Cambridge /bafkrmidpuo45tjd55ndfgg2ipcwgfaxby7paf6em5nw7tbfgo377gfm3re.pdf Jon Sterling 2024 10 23 https://www.forester-notes.org/30FM/ 30FM /30FM/ Forester Blog Jon Sterling 2025 6 15 https://www.forester-notes.org/VNQ9/ VNQ9 /VNQ9/ Rewriting is where the magic happens One question I repeatedly get about Forester is: How do I export a paper written in Forester to a format that I can submit to a journal? It is technically possible to convert Forester’s output XML to LaTeX, using XSLT. There is an outdated stylesheet for that purpose that could be brought up to date. I think this misses something important, though. First of all, what you’ve written in your forest is probably, in form and structure, not a good fit for a journal or conference publication. Second of all, typesetting a publication requires a lot of special-casing and even rewording to avoid things like bad line breaks, etc.; none of that is reflected in the naïve idea of just “exporting your forest to a journal”, but that stuff is very important. I recommend writing in your forest to develop the ideas and explore the space. Then when it is time to fork off a publication, write that story from scratch using a tool that is suited for old-fashioned publication typesetting, like LaTeX. Writing from scratch is not a waste of time; it is the most important part, because you now get to weave together all your insights into a coherent and self-contained narrative that speaks directly to the intended audience of the work in their language; in this process you may adopt notations that are good specifically for that publication, but which you would not wish to expose to (e.g.) a more technical audience, etc. The goals of publishing a traditional article are in total contrast to the goals of writing a forest, which is to leverage the accumulation of interconnected insight (in a necessarily non-self-contained way). There is nothing that I love more about my job as a researcher than taking something I’ve written extensive technical notes on, and then writing the story out linearly from scratch, choosing what to keep and what to omit, how to explain, in what order, and with what notations, for a specific audience. This is where the magic happens. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXS/ QHXS /QHXS/ Intellectual junkyards I was first inspired to create Forester after exploring the Stacks Project and realising that what I most wanted most dearly was the ability and digital space to create my own—and feeling the pain when I tried to install the essentially defunct Gerby software that runs it. Paolo Brasolin was kind enough to help me with this, by building Sheafy on top of Jekyll. I eventually reached the limits of that tool and created Forester on my own (first as a Hugo plugin, and finally as standalone OCaml software). Later I was joined by Kento Okura who has become a strong partner in designing and developing Forester. Whilst exploring the space of tools for thought, I became aware of a cluster of related and deeply inspiring ideas—starting with Andy Matuschak’s evergreen notes which led me to Niklas Luhmann’s Zettelkasten and various kinds of digital gardening. Although all these trends are slightly different and shouldn’t be conflated, the common thread is to accumulate a bunch of small topical notes over many years in hypertext. (Luhmann’s Zettelkasten was of course a physical hypertext, where hyperlinks are hand-written and addressed to locations in his card box, whereas many Zettelkästen today are digital.) Matuschak’s “evergreen” concept refers to the practice of having notes evolve and remain up to date, as opposed to scratch notes that lose salience with time. I was interested enough in the idea that I spent some time thinking about how it might be adapted to the mathematical sciences, and I wrote a manifesto of sorts on the topic: Designing tools for scientific thought. This manifesto guided the design of Forester, whose name was itself inspired by Matuschak’s writings on evergreen notes. For some time now, however, I have been noticing a great deal of friction in my own use of evergreen notes as a tool for advancing science; for this reason, I have been using my own Forest in a different way for some time now. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXT/ QHXT /QHXT/ Life in the junkyard after a few years Let me describe how someone like me predictably starts building up their forest. Because I’m interested in category theory, I start by creating a tree entitled Category with taxon Definition. I start doing the same for other important notions, like functors, natral transformations, etc. Eventually I prove the Yoneda lemma! I spend about a year building up a glorious forest full of category theory. Only then do I realise that ordinary category theory, in which a category is defined to have a set (or a class) of objects, is a mess; I want to switch to univalent category theory which smooths over many of the rough edges. Unfortunately, univalent foundations is very different from set theoretic foundations in subtle ways. I have a plan to refactor my entire forest to account for this, but obviously I have to get my actual work done too. I’ll just hold off on that epic refactoring... I discover an interesting theorem or insight, and I want to write it down in my forest. But my motivation dies when I realise that it would mean adding to the old-and-busted notes, which would increase my future burden when I will definitely (not kidding) update my hundreds of notes. With my motivation killed, I forget about the insight and move on. By the way, not only do I want to switch to univalent categories, I also want to re-do everything in terms of displayed categories. Ouch. This happens enough times, and the forest dies and becomes a junkyard. The End. I suspect this is a somewhat common negative experience with Zettelkästen, but not many people talk about it. In one brave exception, Christian Tietze writes about a similar experience recently with his Zettelkasten, in which he has written a ton of now-outdated notes about subtleties of Apple’s SwiftUI and Observation frameworks. Keeping such things “evergreen” is almost impossible because Apple frameworks are a rapidly moving target. The point I want to make is that mathematics and the sciences are also rapidly moving targets, and if your outlook on them slows its roll long enough for it to become practical to keep a sizable forest evergreen, it may indicate intellectual stagnation more than intellectual wealth. I must also point out that keeping a forest evergreen in this sense does not only amount to updating various trees periodically. One’s mathematical development over time tends to involve not only evolving definitions and proofs, but also an evolution of the entire ontology—which means that the very decision of what to put in one tree and what to put in another tree is difficult to commit to in the long term. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXU/ QHXU /QHXU/ Tree-rings and the dialectics of knowledge production My own experience with the long-term maintenance of a forest or Zettelkasten is that the level of activity therein is uneven over time—there are periods of expansion followed by periods of quiet. In the former, trees tend to cluster around not only a group of related topics but also a particular approach to ontologising those topics. When you encounter one of those trees later on, you can kind of remember when it was written because of the way it was written and the particular relationships you chose to reify in hypertext. Seeing these distinct “rings of growth” emerging in my own forest brought me to the realisation that my viewpoint on evergreen notes might have been overly simplistic. The question seems to be: should we resist the distinctness of intellectual growth rings by hewing to a homogeneity of the present, or should we embrace time and change as fundamental aspects of knowledge production? Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXV/ QHXV /QHXV/ Resist ontology and embrace time Coming back to the difficulty of maintaining a forest in a state of intellectual evolution, I have found that a good approach is to organise my notes around “tracker” trees—which pertain to a particular topic or project but have little content of their own, serving mainly as backlink accumulators for notes written in my private journal, my weeknotes, and my blog. For example, one thing I am working on is Project Pterosaur—which will be a new proof assistant that combines dependent type theory with ideas from Isabelle/HOL. As you can see, there is very little content to the Project Pterosaur tree, but in the private version of my forest there are many backlinks coming from journal entries. I can reconstruct the entire project in my mind by reading through these entries via the backlinks panel, and that to me is far more useful than a (high-churn) “evergreen” note that explains my vision for the project and its status, etc. Obviously this is not a new idea—many people use tools like Obsidian, Logseq, Roam, etc. in the way I am describing. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXX/ QHXX /QHXX/ Blogging is the accretion of temporal insight A few months ago, I had a very enlightening conversation with my colleague Anil Madhavapeddy about blogging. Anil’s research group at Cambridge has a practice of internal blogging and weeknotes: pretty much everyone is writing about their work in blogs that are then syndicated into a Matrix channel. Then, discussion proceeds organically in the chat and in person. These blog posts are not the transient/fleeting notes discussed by Matuschak, because they are not scraps—they are evergreen in the “free” sense of being permanent discourses on a moment in time. For more than a year, I had already been maintaining a personal journal of daily notes in my private forest, but there was always some tension in my writing practices there because I was perfunctorily accumulating “records” of what I did rather than insight. What had not clicked for me at the time was that I really ought to have been blogging (for myself). Journalling in the most progressive sense is simply blogging with a restricted audience, facilitating the accretion of insight more than the mere memory of what happened when. Since my chat with Anil, I have shifted my practice to emphasise semi-public weeknotes whose goal is to provoke and continue discussions that are unfolding within the community that reads them (mainly my colleagues in the Computer Laboratory). Of course, this was only possible after I had added support for syndication to Forester! I still write private entries as well, of course, but not as many. Currently, Forester creates a lot of friction around access control and one of the goals in the coming year or two is to decrease this friction so that one does not have to think so carefully about where to put something that you want to write. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXW/ QHXW /QHXW/ Sprouting shoots, and the Hyperbook I have written above about a forestry practice that embeds time and the evolution of ideas at its core; this is achieved by resisting the packrat’s urge to ontologise every aspect of their intellectual life. This does not mean that static ontologisation has no place; for example, a textbook should not present an evolution of its own ideas (except insofar as it describes history), but should rather present a single unified viewpoint on a topic. Indeed, the original goal of Forester was to simplify the creation and deployment of resources like the Stacks Project and Kerodon, which I will hereafter refer to as hyperbooks. In the hyperbook, we can and must give full play to our instinct for ontologisation, and we are freed from the crushing obligation of permanence by treating a hyperbook in the same way that we treat a blog post: as a unified accretion of insight that pertains to a specific moment in time, making no pretensions as to the universality of the specific ontological approach. This should not surprise anyone who has written books or lecture notes before, but it does represent a retreat from what might now be viewed as an “extremist deviation” in the design of Forester. Prior to Forester 5.0, each person was expected to have just a single forest and all their writings (including lecture notes and hyperbooks!) were expected to be part of that forest. I found that this approach, however, intensifies all the kinds of metal stress that kills motivation and hastens descent into the intellectual junkyard. A better way forward is to liberally split off hyperbooks as independent forests—which can then be federated with your own forest (please note that this functionality is experimental and subject to change). The ability to federate forests is important, because otherwise one would have to choose between bidirectional linking and modularity; with federation, there is no need to make this choice. Splitting off forests in Forester 5.0 still involves some annoying points of friction; the biggest one is the need for global identity that spans all forests. A solution to this problem will not ship with 5.0, but I am preparing to work on it for a subsequent release. Jon Sterling 2025 5 27 2025 5 30 https://www.forester-notes.org/QHXY/ QHXY /QHXY/ Renew life, have a forest fire! The goal of the Forester project has always been to reduce mental stress and release untapped stores of creativity in the struggle for outlook and insight. In some sense, every iteration of Forester has been an experiment from which we are taking both positive and negative lessons. Some users of Forester have adopted extreme ontological practices (abetted, perhaps regrettably, by our dangerously powerful Datalog query engine). It is not my place to prescribe how people should use Forester, but I do care for people’s well-being and I strongly believe that these kinds of practices can destroy the mind over time. If you are feeling the weight of ontology in a heavy-laden forest, there is nothing wrong with a little forest fire. When the smoke clears, start a blog. Jon Sterling 2025 3 25 https://www.forester-notes.org/JVIT/ JVIT /JVIT/ Towards Forester 5.0 II: a design for canonical URLs One of the goals of Forester 5.0 is lightweight federation—the ability to have two forests participate in the same graph and therefore provide backlinks, etc. In a previous post (Towards Forester 5.0: a design for global identity), I talked about some of the difficulties that arise when dealing with identities of people and references that have global scope but could nonetheless be described by trees in many forests. I proposed that such things should be addressed by canonical URIs (e.g. DIDs, DOIs, etc.) and that Forester should grow the ability to bind a canonical URI to multiple trees, which are then gathered into a disambiguation page. Today I want to broaden the discussion to cover the difficulties of addressing trees themselves (as opposed to the global entities they may describe). This is a proposal and I welcome feedback. Jon Sterling 2025 3 25 https://www.forester-notes.org/JVIU/ JVIU /JVIU/ Forester must become part of the Web I have been working on developing the prerequisites for Forester to emit RSS and Atom feeds for blogs, and I realised that the problem I was trying to solve earlier this month is a more multifaceted than I originally thought. It comes down to analysing what is needed for Forester to be a good citizen of the World Wide Web: in particular, if we emit an RSS feed that has hyperlinks to some trees in it, those links must refer to an actual page on the actual web rather than something specific to Forester’s ontology. This may seem downright obvious in hindsight, but you must understand that for the longest time I was not thinking of Forester as a tool for progressively enhancing the Web, but rather as a tool for building fully-local life-wikis or Zettelkästen; I no longer believe that my former viewpoint is reasonable, and I have concluded that we must integrate Forester into the Web or else we will be buried under friction. This post is the start of a design for how to do this. Forget what you know about how either Forester 5.0 or previous versions currently work; in order to solve these problems in a reasonable way, we cannot be bound by the past versions of an experimental tool. What we are bound by is the architecture of the World Wide Web, and that will be reflected in the design. Jon Sterling 2025 3 25 https://www.forester-notes.org/JVIV/ JVIV /JVIV/ What is the proposal? Here is the essence of the proposal: We get rid of the forest://host/addr scheme. Instead, trees are globally addressed by a canonical URL. The canonical URL of a tree can in principle be arbitrary, but in practice you will want it to be a place where that tree can be viewed — e.g. the place to which it will be uploaded and served via HTTP(S). Indeed, a default scheme will be provided so as to enable files to be rendered with names and relative locations consistent with the intended global addressing scheme; it is also possible to imagine customisation of this without disturbing the overall design. The canonical URLs are now the vertices of the graph. In Forester source code, a hyperlink like would be resolved right away to or something, using information supplied in the user’s forest; the same goes for transclusion. Links to trees in foreign forests must, for now, be totally explicit (but we can imagine relaxing this in the future). Importantly, this approach does not require knowing what is in the forest at evaluation-time. Jon Sterling 2025 3 25 https://www.forester-notes.org/JVIW/ JVIW /JVIW/ What about replication and mirroring? It may seem annoying to have canonical URLs. For example, a forest that contains vital information might need to be published in multiple places. That much is true, but the fact that the physical publication of a forest is replicated should not allowed to impact the graph or fill it with redundant vertices and edges (e.g. should two mirrors become federated). So the only problem with replication is that hyperlinks might take you to the original forest instead of keeping you in the mirror, but I think this should be resolved by some kind of middleware that rewrites links, just as the Wayback machine rewrites links in its snapshots. That can be handled outside of Forester. Jon Sterling 2025 3 25 https://www.forester-notes.org/JVIX/ JVIX /JVIX/ What about viewing my forest locally? Most of the time, an author is working with their forest on their own machine rather than on the web. It is important that links and transclusions point to the local content rather than whatever (if anything) is stored in the “global” canonical URL. I believe this is not actually a problem: although things like RSS feeds and perhaps even published websites would have all the hyperlinks point to the canonical URLs, there is no reason that this should be required for all renderers. It is easy to imagine making this a configurable flag for the default renderer, and for the upcoming “dynamic”/interactive HTML server we would emit links back to the local server rather than to the canonical URLs. Similarly, there may be projects where there is no intention at all of online publication. In such cases, the scheme for assigning canonical URLs can be arbitrary. Jon Sterling 2025 3 25 https://www.forester-notes.org/JVIY/ JVIY /JVIY/ What about access control? Forester does not currently support any kind of access control, but this is indeed an important area that we are considering carefully in order to enable institutional use of Forester, and ease the burden of collaboration in the usual case of a forest that contains a mixture of data with varying levels of confidentiality. I believe that the current design is compatible with essentially any approach to access control that we might adopt, but I am interested in feedback to the contrary. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOJ/ OYOJ /OYOJ/ Towards Forester 5.0: a design for global identity As we move closer to Forester 5.0, which introduces rudimentary federation capabilities, we must address new problems that did not arise in the days when no two forests interacted or linked to each other. The most immediate issue is that trees describing entities with “global” identity (including actual people as well as bibliographic references) will naturally be duplicated across many forests. For example, this happens when one person authors trees in multiple forests, and it happens even more often with bibliographic entries (both for the entries themselves and their author attributions). It is very important to handle this problem properly now in a way that (1) minimises friction and (2) enables us to quietly evolve toward more Web-centric approaches to identity as they emerge. Below, I survey some existing approaches to identity that we would hope to be compatible with at some level. If you want to skip to my concrete proposal, see § . Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOL/ OYOL /OYOL/ Survey of global identification schemes There are several extant schemes for identifying individuals, organisations, and artefacts. Some are centralised, and others are decentralised. Centralisation of identity is not necessarily a bad thing, but it is most viable when nearly everyone agrees on the central authority; on the other hand, decentralisation can help in situations where a single central authority has not accumulated enough trust or prestige to be viable. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOM/ OYOM /OYOM/ Centralised identification via DOIs and ORCIDs Nearly every scholarly paper and book published has a Digital Object Identifier (DOI) assigned to it, which are managed by a single authority (The DOI Foundation); this applies to both traditional publishers and eprint servers like the arXiv. Services like Zenodo allow individuals to mint their own DOIs and pin resources and artefacts to them. Due to their widespread adoption, DOIs are a completely viable way to identify published papers and books—and I would argue that any attempt to replace DOIs with a decentralised identifier is likely to be counterproductive as the goal should not not be decentralisation per se but rather to have a reliable, universal way to refer to scholarly content and artefacts. What DOIs do for artefacts, the Open Researcher and Contributor ID (ORCID) aims to do for people acting within the framework of open science. ORCIDs seem to do their job well, but not everyone has or should have an ORCID—nor would every person who does have one voluntarily choose to pin their entire identity to it. Therefore, although I happily use them, I think ORCIDs are likely to face more of an uphill battle than the DOI—which needed buy-in only from major publishers and eprint servers to reach hegemony. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOK/ OYOK /OYOK/ Informal decentralised identification via web addresses A particularly simple way to identify a single person or organisation is by means of a web domain or an email address. Although not everyone has a domain name, many people have email addresses. On the other hand, people often have many domain names and their email address may change over time; and when people die, their presence on the web is often erased or lost. Therefore, although widespread, this approach may create difficulties with longevity and stability. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYON/ OYON /OYON/ General-purpose decentralised identification via DIDs When reading about the paper of Klepmann et al. outlining Bluesky’s AT Protocol, I learned of Decentralised Identifiers (DIDs). In essence, DIDs are URIs of the form did:method:path where method identifies how the DID is intended to be resolved and path is a colon-separated path that should be resolved by means of that method. In either case, a DID is intended to be resolved to a JSON document that contains information about the resource or entity being described, as well as various methods (like public keys) for verifying the integrity of that information. The methods are somewhat open-ended, but two important methods have emerged. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOO/ OYOO /OYOO/ W3C’s did:web method W3C have specified the did:web method, which in which the path is intended to be a web domain. Simplifying somewhat, a DID like did:web:jonmsterling.com would be substantiated by responding to the HTTPS request https://jonmsterling.com/.well-known/did.json with a document in the appropriate format. The upside is that the owner of a web domain is their own identity authority; in this sense did:web is a truly decentralised identification scheme. The downside is that you have to have a web domain, and you also can never change it ever—the same disadvantage of informal decentralised identification which we have discussed. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOP/ OYOP /OYOP/ Bluesky’s did:plc method For a social network like Bluesky, it is critical that users be able to migrate their identity from one domain to another. Obviously users may change or lose their domain over time, but it is important to keep in mind that the vast majority of users will never have their own domain and so they will over the course of their lives jump from one subsidiary domain that they don’t control to the next—just as Mastodon users are constantly migrating from instance to instance, driven to wander endlessly by either the petty tyranny of instance maintainers who think they know best, or by the natural quiescence of instances caused by lack of funds or time, or (in many cases) a combination of the two. It seems that there is no way to address this problem without introducing some central authority—a directory of permanent identifiers that are then resolved to documents that establish cryptographically verified bidirectional links with more ephemeral and human-readable forms of identification (such as web domains). This is essentially the design of Bluesky’s did:plc method, as explained by Klepmann et al.: On your own domain, which serves as your (ephemeral) handle, you place a DNS TXT record or file that contains a DID like did:plc:asdlkfh9q8034baliufhbcailurb. Someone resolves this DID to a document by querying a central directory server (such as Bluesky’s own). This document contains a link back to the domain; signatures are used to ensure that every update to the document has been authorised by whoever signed it when it was first minted. Although some centralisation is required here, the use of cryptographic proof ensures that the central authority does not need to be trusted (to a certain extent). Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOQ/ OYOQ /OYOQ/ Analysis of global identity in Forester Although Forester aims to become a better citizen of the Web and integrate with emerging protocols, it is a non-negotiable design constraint that Forester still remain usable by people who don’t control a domain name, cannot run software on their web host, cannot set DNS records, and could not care less what a DID is. I also have a feeling that there will not be a single protocol that fits all use cases; what I am noticing, however, is that there are commonalities to all the protocols, and that we ought to be informed by these commonalities. For example, in every case an identity is resolved from a URI of some kind—for example, DIDs and DOIs and ORCIDs all have canonical URIs. Therefore, it strikes me that Forester’s approach to global identity must rest on the axiom that an identity is nothing more or less than a URI; we can place no constraints whatsoever on what form this URI takes, and we should also remain flexible as to compatibility with future replacements of URIs (whether in the form of IRIs, or the URL non-“standard”, etc.). If we start from that point of view, there some problems to address: Even if an identity is not canonically addressed by a tree in a forest, an identity still often needs to have a tree in the forest. One wants to store biographical and bibliographic information, and maybe even personal notes, etc., and at the very least it is very important to be able to browse backlinks on a biographical page even if the page itself has no content of its own. Not only must we be able to attach a tree to an identity: we must be able to attach many trees to an identity. This is a requirement of federation. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOR/ OYOR /OYOR/ A plan for global identity in Forester Building on my analysis, I propose that Forester allow any tree to declare that it “describes” a given global identity in the form of a URI. At a first cut this can be done via datalog (but we would probably hide this behind something): Now it remains to explain how we shall surface the fact that a given entity is described by some tree. For any identity in this relation, we should automatically create a “disambiguation page” that transcludes all the attached trees. When a hyperlink points to a URI that lies in this relation, it should be directed to the disambiguation page. There are further implications for such a feature—for instance, in the future we might automatically populate bibliographic information, etc. (But we have to be careful due to the near-universal unusably low quality of bibliographic databases keyed by DOIs, etc.) We will need to provide guidance as to how identities should be assigned to (e.g.) people who don’t control an online identity, etc. The rule of thumb should be that we always defer to the preferences of the described person, and to the version of record in the case of an artefact. When there is no canonical choice, users of Forester should do what they like, but they should be willing to update their references in the future should a canonical global entity emerge. Jon Sterling 2025 3 8 https://www.forester-notes.org/OYOS/ OYOS /OYOS/ Request for comment I am hoping to hear other people’s thoughts on this proposal, including any constructive criticisms or suggestions for how we might go about implementing it. You can write to me or the mailing list with your feedback. Jon Sterling 2023 5 14 2024 4 25 2025 5 26 https://www.forester-notes.org/0052/ 0052 /0052/ Build your own Stacks Project in 10 minutes The Stacks project is the most successful scientific hypertext project in history. Its goal is to lay the foundations for the theory of algebraic stacks; to facilitate its scalable and sustainable development, several important innovations have been introduced, with the tags system being the most striking. Each tag refers to a unique item (section, lemma, theorem, etc.) in order for this project to be referenceable. These tags don't change even if the item moves within the text. (Tags explained, The Stacks Project). Many working scientists, students, and hobbyists have wished to create their own tag-based hypertext knowledge base, but the combination of tools historically required to make this happen are extremely daunting. Both the Stacks project and Kerodon use a cluster of software called Gerby, but bitrot has set in and it is no longer possible to build its dependencies on a modern environment without significant difficulty, raising questions of longevity. Moreover, Gerby’s deployment involves running a database on a server (in spite of the fact that almost the entire functionality is static HTML), an architecture that is incompatible with the constraints of the everyday working scientist or student who knows at most how to upload static files to their university-provided public storage. The recent experience of the nLab’s pandemic-era hiatus and near death experience has demonstrated with some urgency the pracarity faced by any project relying heavily on volunteer system administrators. Jon Sterling 2023 5 14 https://www.forester-notes.org/0053/ 0053 /0053/ Introducing Forester: a tool for scientific thought After spending two years exploring the design of tools for scientific thought that meet the unique needs of real, scalable scientific writing in hypertext, I have created a tool called Forester which has the following benefits: Forester is tag-based like Gerby, and can therefore power large-scale generational projects like Stacks and Kerodon. Forester produces static content that can be uploaded to any web hosting service without needing to run or install any serverside software. Forester is easy to install on your own machine. To prevent bitrot, Forester is a single tool rather than a composition of several tools. Forester satisfies all the requirements of serious scientific writing, including sophisticated notational macros, typesetting of diagrams, etc. Forester combines associative and hierarchical networks of evergreen notes (called “trees”) into hypertext sites called “forests”. Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000R/ tfmt-000R /tfmt-000R/ Forests and trees of evergreen notes Definition A forest of evergreen notes (or a forest for short) is loosely defined to be a collection of evergreen notes in which multiple hierarchical structures are allowed to emerge and evolve over time. Concretely, one note may contextualize several other notes via transclusion within its textual structure; in the context of a forest, we refer to an individual note as a tree. Of course, a tree can be viewed as a forest that has a root node. Trees correspond roughly to what are referred to as “tags” in the Stacks Project. In this article, I will show you how to set up your own forest using the Forester software. These instructions pertain to the Forester 5.0 version. Jon Sterling 2023 8 13 https://www.forester-notes.org/006R/ 006R /006R/ Preparing to run the Forester software In this section, we will walk through the installation of the Forester software. Jon Sterling 2023 8 13 https://www.forester-notes.org/006S/ 006S /006S/ System requirements of Forester Jon Sterling 2023 8 13 https://www.forester-notes.org/006T/ 006T /006T/ A unix-based system Requirement Forester requires a unix-based system to run; it has been tested on both macOS and Linux. Windows support is desirable, but there are no concrete plans to implement it at this time. Jon Sterling 2023 8 13 https://www.forester-notes.org/006U/ 006U /006U/ A working OCaml 5 installation Requirement Forester is written in the OCaml programming language, and makes use of the latest features of OCaml 5. Most users should install Forester through OCaml's opam package manager; instructions to install opam and OCaml simultaneously can be found here. Jon Sterling 2023 8 13 https://www.forester-notes.org/006V/ 006V /006V/ A working installation Requirement If you intend to embed -rendered diagrams in your forest, you will need to have a working installation of installed, such as TeX Live. If all your mathematical expressions are supported by , this is not necessary. Jon Sterling 2023 8 14 https://www.forester-notes.org/006Y/ 006Y /006Y/ The git distributed version control system Requirement It is best practice to maintain your forest inside of distributed version control. This serves not only as a way to prevent data loss (because you will be pushing frequently to a remote repository); it also allows you to easily roll back to an earlier version of your forest, or to create “branches” in which you prepare trees that are not yet ready to be integrated into the forest. The recommended distributed version control system is git, which comes preinstalled on many unix-based systems and is easy to install otherwise. Git is not the most user-friendly piece of software, unfortunately, but it is ubiquitous. It is possible (but not recommended) to use Forester without version control, but note that the simplest way to initialize your own forest involves cloning a git repository. Jon Sterling 2023 8 13 https://www.forester-notes.org/006W/ 006W /006W/ Installing the Forester software Once you have met the system requirements, installing Forester requires only a single shell command: To verify that Forester is installed, please run forester --version in your shell. Jon Sterling 2023 8 14 2024 4 25 2024 6 17 https://www.forester-notes.org/006X/ 006X /006X/ Setting up your forest from the template Now that you have installed the Forester software, it is time to set up your forest. Forester provides a simple command to initialise a fresh forest within a folder. We’ll call our folder forest, but you can call it anything you want. Now that we are inside our new directory, we can instruct Forester to initialise a forest. forester init This command initialises a git repository with the skeleton of a forest, which contains a configuration file named forest.toml; this file specifies the locations of your trees, assets, etc. There is also a git submodule bound to the theme/ directory (pointing to the base theme repository) that contains the stylesheets that web browsers will need in order to render your forest as HTML. Jon Sterling 2023 8 14 2024 6 17 https://www.forester-notes.org/0073/ 0073 /0073/ Tree addresses in a forest A tree in Forester is usually associated to an address of the form NNNN is a four-digit base-36 number. The purpose of the base-36 code is to uniquely identify a tree within your forest in such a way that you are not tempted to rename it, as you might be when titles or dates are embedded into filenames. A tree with address NNNN is stored in a file named NNNN.tree (unless it is emitted from inside another tree by means of the inline subtrees feature). Note that the format of tree addresses is purely a matter of convention, and is not forced by the Forester tool. Users are free to use their own naming convention for tree addresses, and in some cases alternative (human-readable) formats may be desirable: this includes trees representing bibliographic references, as well as biographical trees. If you don’t like numerical tree addresses, nobody is forcing you to use them. The use of numerical addresses is suitable for projects like The Stacks Project, but it may not be appropriate for your own use-case. Addresses in Forester are not hierarchical: all resources are rendered at the root of the forest, no matter where their source files are kept. This limitation is intentional, but we might revisit it in the future. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007D/ 007D /007D/ Building and viewing your forest for the first time To build your forest, you can run the following command of Forester's executable in your shell: forester build forest.toml The --dev flag is optional, and when activated supplies metadata to the generated website to support an “edit button” on each tree; this flag is meant to be used when developing your forest locally, and should not be used when building the forest to be uploaded to your public web host. Jon Sterling 2023 8 15 https://www.forester-notes.org/007G/ 007G /007G/ Forester renders each tree to an XML document Forester renders your forest to some XML files in the output/ directory; XML is, like HTML, a format for structured documents that can be displayed by web browsers. The forest template comes equipped with a built-in XSLT stylesheet (theme/default.xsl) which is used to instruct web browsers how to render your forest into a pleasing and readable format. Jon Sterling 2023 8 15 https://www.forester-notes.org/007I/ 007I /007I/ Serving and viewing your forest from a local web server To view your forest while editing it, you must serve it from a local web server..To do this, first ensure that you have Python 3 correctly installed. Then run the following command from the root directory of your forest: python3 -m http.server 1313 -d output (You could replace 1313 with whatever port you prefer.) While this command is running, you will be able to access your forest by navigating to localhost:1313 in your preferred web browser. In the future, Forester may be able to run its own local server to avoid the dependency on external tools like Python. Jon Sterling 2023 8 15 https://www.forester-notes.org/007K/ 007K /007K/ Creating your personal biographical tree The first tree that you should create is a biographical tree to represent your own identity; ultimately you will link to this tree when you set the authors of other trees that you create later on. It is convenient to simply use a person’s full name to address a biographical tree. My own biographical tree is located at trees/people/jonmsterling.tree and contains the following source code: Let’s break this code down to understand what it does. The declaration sets the title of the tree to my name. The declaration informs Forester that the tree is biographical. Not ever tree needs to have a taxon; common taxa include Person, Theorem, Definition, Lemma, etc. You are free to use whatever you want, but some taxa are treated specially by Forester. The subsequent declarations attach additional information to the tree that can be used during rendering. These declarations are optional, and you are free to put whatever metadata you want. Like in HTML, paragraphs must be wrapped in . Do not hard-wrap your text, as this can have visible impact on how trees are rendered; it is recommended that you use a text editor with good support for soft-wrapping, like Visual Studio Code. You can see that the concrete syntax of Forester's trees looks superficially like a combination of and Markdown; Markdown-style links are used both for links to other trees and for links to external URLs. Forester's concrete syntax is not fully documented, but it is less ambiguous than both and Markdown. Jon Sterling 2023 8 15 2024 4 25 https://www.forester-notes.org/007H/ 007H /007H/ Creating a new tree using forester new Creating a new tree in your forest is as simple as adding a .tree file to the trees folder. Because it is hard to manually choose the next incremental tree address, Forester provides a command to do this automatically: forester new forest.toml --dest=trees In return, Forester should output the location of the new tree, e.g. trees/0002.tree. If we look at the contents of this new file, we will see that it is empty except for metadata assigning a date to the tree: You may prefer to use randomised addresses over sequential addresses; this can be particularly useful if multiple people are contributing to a forest. In that case, pass the --random option to forester new. Most trees should have a annotation; this date is meant to be the date of the tree's creation; you can have more than one date, if you like to keep track of when a tree has been updated. You should proceed by adding further metadata: the title and the author; for the latter, you will use the address of your personal biographical tree. Tree titles should be given in lower case (except for proper names, etc.); these titles will be rendered by Forester in sentence case. A tree can have as many declarations as it has authors; these will be rendered in their order of appearance. Now you can begin to populate the tree with its content, written in the Forester markup language. Think carefully about keeping each tree relatively independent and atomic. Jon Sterling 2023 8 15 https://www.forester-notes.org/007L/ 007L /007L/ Bottom-up hierarchy via transclusion You may be used to writing documents, where you work from the top down: you create some section headings, put some text under those headings, make some deeper section headings, put more text, etc. Forests work in the opposite way, from the bottom up: you start by writing independent, atomic notes/trees and then only later start to (sparingly) assemble these into a hierarchy in order to reify the emerging structure. Forester’s bottom-up approach to section hierarchy works via something called transclusion. The idea is that at any time, you can include (“transclude”) the full contents of another tree into the current tree as a subsection by adding the following code: This is kind of like ’s command, but much better behaved: for instance, section levels are computed on the fly depending on the position in the hierarchy. This entire tutorial is cobbled together by transcluding many smaller trees, each with their own independent existence. For example, the following two sections are transcluded from an entirely different part of my forest: Jon Sterling 2022 12 27 https://www.forester-notes.org/tfmt-0009/ tfmt-0009 /tfmt-0009/ The best structure to impose is relatively flat It is easy to make the mistake of prematurely imposing a complex hierarchical structure on a network of notes, which leads to excessive refactoring. Hierarchy should be used sparingly, and its strength is for the large-scale organization of ideas. The best structure to impose on a network of many small related ideas is a relatively flat one. I believe that this is one of the mistakes made in the writing of the foundations of relative category theory, whose hierarchical nesting was too complex and quite beholden to my experience with pre-hypertext media. One of the immediate impacts and strengths of Forester’s transclusion model is that a given tree has no canonical “geographic” location in the forest. One tree can appear as a child of many other trees, which allows the same content to be incorporated into different textual and intellectual narratives. Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0006/ tfmt-0006 /tfmt-0006/ Hierarchical structure as non-unique narrative Multiple hierarchical structures can be imposed on the same associative network of nodes; a hierarchical structure amounts to a “narrative” that contextualizes a given subgraph of the network. One example could be the construction of lecture notes; another example could be a homework sheet; a further example could be a book chapter or scientific article. Although these may draw from the same body of definitions, theorems, examples, and exercises, these objects are contextualized within a different narrative, often toward fundamentally different ends. As a result, any interface for navigating the neighbor-relation in hierarchically organized notes would need to take account of the multiplicity of parent nodes. Most hypertext tools assume that the position of a node in the hierarchy is unique, and therefore have a single “next/previous” navigation interface; we must investigate the design of interfaces that surface all parent/neighbor relations. Jon Sterling 2023 8 16 https://www.forester-notes.org/007N/ 007N /007N/ The Forester markup language A tree in Forester is a single file written in a markup language designed specifically for scientific writing with bottom-up hierarchy via transclusion. A tree has two components: the frontmatter and the mainmatter. Jon Sterling 2023 8 16 https://www.forester-notes.org/007P/ 007P /007P/ Forester markup: frontmatter The frontmatter of a Forester tree is a sequence of declarations that we summarize below. Declaration Meaning sets the title of the tree; can contain mainmatter markup sets the author of the tree to be the biographical tree at address name sets the creation date of the tree; full ISO 8601 date-times are supported. sets the taxon of the tree; example taxa include lemma, theorem, person, reference; the latter two taxa are treated specially by Forester for tracking biographical and bibliographical trees respectively defines and exports from the current tree a function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for brings the functions exported by the tree address into scope brings the functions exported by the tree address into scope, and exports them from the current tree Jon Sterling 2023 8 16 https://www.forester-notes.org/007O/ 007O /007O/ Forester markup: mainmatter Below we summarize the concrete syntax of the mainmatter in a Forester tree. Function Meaning creates a paragraph containing ...; unlike Markdown, it is mandatory to annotate paragraphs explicitly typesets the content in italics typesets the content in boldface creates an ordered list creates an unordered list creates a list item typesets the content in (inline) math mode using ; note that math mode is idempotent in Forester typesets the content in (display) math mode using transcludes the tree at address address as a subsection formats the text title as a hyperlink to address address; if address is the address of a tree, the link will point to that tree, and otherwise it is treated as a URL defines a local function named with two arguments; subsequently, the expression would expand to body with the values of u,v substituted for . typesets the content in monospace typesets the body externally using using preamble as preamble code (e.g. to set up tikz packages, etc.). It can be useful to wrap this in your own macro in order to insert your preamble code automatically. Jon Sterling 2023 8 16 https://www.forester-notes.org/007Q/ 007Q /007Q/ An complete worked example tree in Forester Example An example of a complete tree in the Forester markup language can be seen below. The code above results in the following tree: Jon Sterling 2023 2 11 https://www.forester-notes.org/001H/ 001H /001H/ Creation of (co)limits Definition Let be a functor and let be a category. The functor is said to create (co)limits of -figures when for any diagram such that has a (co)limit, then has a (co)limit that is both preserved and reflected by . Jon Sterling 2023 8 16 https://www.forester-notes.org/007R/ 007R /007R/ Deploying your forest to a web host Now that you have created your forest and added a few trees of your own, it is time to upload it to your web host. Many users of Forester will have university-supplied static web hosting, and others may prefer to use GitHub pages; deploying a forest works the same way in either case. First, make sure your forest is built using the earlier instructions. Then take the entire contents of your output directory and upload them to your preferred web host. Jon Sterling 2023 8 16 https://www.forester-notes.org/007S/ 007S /007S/ Let a hundred forests bloom! I am eager to see the new forests that people create using Forester. I am happy to offer personal assistance via the mailing list. Many aspects of Forester are in flux and not fully documented; it will often be instructive to consult the source of existings forests, such as this one. Have fun, and be sure to send me links to your forests when you have made them! https://www.forester-notes.org/jonmsterling/ jonmsterling /jonmsterling/ Jon Sterling Person https://www.jonmsterling.com/ University of Cambridge 0000-0002-0585-5564 Associate Professor https://www.forester-notes.org/kentookura/ kentookura /kentookura/ Kento Okura Person https://github.com/kentookura Jon Sterling 2023 6 20 https://www.forester-notes.org/0065/ 0065 /0065/ Forester › Project information code forge: sr.ht/~jonsterling/forester ticket tracker: todo.sr.ht/~jonsterling/forester mailing lists: sr.ht/~jonsterling/forester/lists opam package: ocaml.org/p/forester tutorial: How to create your own Stacks Project in 10 minutes Jon Sterling Armaël Guéneau Jinser Kafka Kento Okura Kuen-Bang Hou (Favonia) Lîm Tsú-thuàn Nick Hu Owen Lynch Patrick Nicodemus Riley Shahar Trebor Huang 2023 6 1 https://www.forester-notes.org/005P/ 005P /005P/ Forester › Release notes A tool for tending forests of evergreen notes.Jon Sterling2023620https://www.forester-notes.org/0065/0065/0065/Forester › Project information code forge: sr.ht/~jonsterling/forester ticket tracker: todo.sr.ht/~jonsterling/forester mailing lists: sr.ht/~jonsterling/forester/lists opam package: ocaml.org/p/forester tutorial: How to create your own Stacks Project in 10 minutes Kento Okura2026212https://www.forester-notes.org/VNQB/VNQB/VNQB/Forester 6.0ReleaseWe thank Tarides and the OCaml Software Foundation for their financial support enabling this release.Jon SterlingKento Okura20241020https://www.forester-notes.org/011P/011P/011P/Forester 5.0ReleaseThis is a major release of Forester that includes many changes under the hood, as well as breaking changes that will require manual adjustments to existing forests. We are sorry for the frustration that these changes may cause to existing users, but we strongly believe that this is necessary for Forester to reach its potential as a tool that enhances rather than replaces the World Wide Web; we also strongly believe that these changes will make Forester more useful for existing users as well as the next thousand users.Our thanks to Owen Lynch, davidad, and Anil Madhavapeddy for conversations leading to the design of this release. We are grateful to ARIA’s Safeguarded AI initiative for helping us get to 5.0.Many of the changes included here are meant to support the future of Forester as an authoring tool for a new kind of Internet of Science that will enable the federation of many different forests by extending existing protocols with new hypermedia controls for content transclusion applicable to scientific authoring.Jon SterlingKento Okura20241020https://www.forester-notes.org/0126/0126/0126/Tl;dr: migration guideTo migrate your forest to Forester 5.0, do the following:Update your configuration file (§ ). Take into account changes to the source language (§ ). Any or attributions must take a tree address as their argument; when you wish to attribute a resource to a person who is not represented by a tree, you can use or (see § ). Rewrite any queries to use the new datalog engine (see § ), as the legacy query engine has been removed. Take into account the renaming of several built-in relations (see § ). View your forest locally using an HTTP server rather than directly through the file system (see § ). Begin dialing back your use of custom XML stylesheets (see § ). It is possible that support for customisation at this level will be removed in a future release; if you have innovative customisations that are very important for your use of Forester, consider discussing them on the mailing list so that maintainers can better understand the problems you are solving.Jon SterlingKento Okura20241020https://www.forester-notes.org/0SOW/0SOW/0SOW/An implementation of the language server protocolForester now ships with an implementation of the language server protocol. See our documentation for more information and configuration examples for various editors. Its status is still experimental. If you encounter crashes or other issues, please let the us know by opening an issue or by writing to the mailing listJon SterlingKento Okura20241020https://www.forester-notes.org/0125/0125/0125/Changes to forest.toml formatSeveral changes have been made to the forest.toml configuration format.forest.root is renamed to forest.home. The forest.theme key has been removed; from now on, your theme must be located in the theme directory. A new field forest.foreign has been added; this is the entry-point for the experimental forest syndication feature discussed in § .Jon SterlingKento Okura20241020https://www.forester-notes.org/011Q/011Q/011Q/Canonical URLs for tree addressesUp until this release, Forester’s trees were addressed by short strings — which, by convention, might be of the form xxx-NNNN or NNNN or some arbitrary string like sterling-2021-thesis. In order to prepare for the future in which multiple forests can be glued together, we replace Forester’s short names with fully qualified URLs that point to the location on the World Wide Web where a given tree would be published (if you choose to publish it). By default, all local trees will be resolved against http://forest.local/, which you should change if you choose to publish your forest on the Web. In your forest.toml configuration, first set a base URL for your forest like the following:Within this forest, a tree named foo is then associated to the canonical URL https://www.forester-notes.com/foo/. Forester’s renderer will produce the correct directory structure so that if you were to upload the contents of the output directory to https://www.forester-notes.com/, a link to https://www.forester-notes.com/foo/ would bring you to the foo tree.Hyperlinks in Forester source code to trees within your own forest will automatically expand the short name foo to the canonical URL https://www.forester-notes.com/foo/. Canonical URLs are used as vertices in the graph.Jon SterlingKento Okura20241020https://www.forester-notes.org/011R/011R/011R/What do we mean by “URL”?Today, “URLs” are a mostly implementation-defined concept that can only be understood by looking at the source code of major web browsers; in the future, this may congeal into an actual standard but today is not that day (nor is tomorrow, if the state of the whatwg/url “living” [non-]standard is any indication). It is best to think of Forester’s approach to URLs as provisional and subject to evolution as the Web continues to mature.Jon SterlingKento Okura20241020https://www.forester-notes.org/OYOT/OYOT/OYOT/Simplifications to the source languageJon SterlingKento Okura20241020https://www.forester-notes.org/OYOU/OYOU/OYOU/Removal of imports within subtreesIt is no longer permitted to have an declaration within a subtree: these can occur only at the top level of a file and therefore have file-level scope.Jon SterlingKento Okura20241020https://www.forester-notes.org/011T/011T/011T/Removing transclusion overridesIn prior versions of Forester, it was possible to override the title and the taxon of a transcluded tree using the fluid bindings and respectively. This feature is no longer supported in Forester 5.0, and existing users are encouraged to purge their use of it prior to upgrading to Forester 5.0.In short, supporting this feature was greatly complicating the planned transition to a genuine hypermedia format; it could also be argued that it might have led to scenarios where an original author’s intentions are violated at the transclusion site.Please note that transclusion options, such as , etc., are still supported.Jon SterlingKento Okura20241020https://www.forester-notes.org/OYOV/OYOV/OYOV/Removal of autocapitalisationTitles and taxa will no longer be autocapitalised: this feature biases Forester toward specific languages and is annoyingly complex to maintain. Therefore, you must rename all your titles and taxa to be capitalised by hand. This can be done in VS Code using the following regexp: replace with , etc.Jon SterlingKento Okura20241020https://www.forester-notes.org/OYOW/OYOW/OYOW/Changes to fallthrough behaviour for undefined identifiersPreviously, an undefined identifier like would be emitted verbatim as text rather than raising a warning. The reasoning behind this was to smoothly support referring to existing commands in TeX-like environments (including KaTeX and embedded LaTeX). The trade-off was that authors would not receive warnings about what were in many cases typographical errors.In Forester 5.0, the fallthrough behaviour of undefined identifiers is now restricted to code that is evaluated within a TeX-like environment (either KaTeX or embedded LaTeX). In all other cases, a warning will be emitted. This involves a trade-off, because the arguments to a macro like are evaluated first outside the math scope. Therefore, a call like written outside of a math scope would result in a warning. The recommended solution to this problem is to use a lazy argument, which will be evaluated in CBN. Here is an updated version of the macro that works uses a lazy argument:The design is admittedly imperfect, but I believe this is an improvement as it allows us to catch more typos. I expect that the handling of undefined identifier fallthrough will continue to evolve.Jon SterlingKento Okura20241020https://www.forester-notes.org/012N/012N/012N/Changes to attribution linksIn prior versions, the and command would detect whether its contents were the address of a tree; if so, it would create a wikilink to the tree and otherwise, the included text would appear directly. This feature was convenient for smoothly handling the case that an author of a given resource is not represented in the forest by a biographical tree; the downside is that it makes the assumption that at compiletime we shall know the entire contents of the forest (and, thus, whether a given address shall be bound to a tree).To simplify the handling of author links and make it compatible with the open-world future of Forester, the behaviour is changed as follows:The argument to and must be a (possibly relative) Forester URL. Thus, on my own forest, it would be OK to have either or but it would not be OK to have . To make an unlinked attribution containing, use .Jon SterlingKento Okura20241020https://www.forester-notes.org/013A/013A/013A/New datalog-based query engineAs the query engine has evolved, it has become a bit unwieldy and misshapen. In order to prevent further churn and facilitate the long-term development and use of Forester, we are replacing the query engine and graph analysis with a more general tool: datalog. With this change comes the ability to introduce arbitrary relations of any arity; this is a powerful and dangerous tool, so use it wisely.Jon SterlingKento Okura20241020https://www.forester-notes.org/013B/013B/013B/On performance trade-offsSwitching to datalog makes forests that make heavy use of queries a bit slower to render. We considered this trade-off carefully, but believe that for the long-term health of Forester, this is acceptable. In the near future, Forester will render trees on demand rather than all at once (except when you are preparing a static archive for upload/deployment); in this mode of use, Forester will be faster than ever.Jon SterlingKento Okura20241020https://www.forester-notes.org/013C/013C/013C/Renamed built-in relationsForester’s built-in binary relations have been accessible via macros like , etc. In this release, these relations are being renamed to make them more pleasant and consistent to use with datalog. Old name New name rel/tags rel/has-tag rel/taxa rel/has-taxon rel/authors rel/has-author rel/contributors rel/has-direct-contributor rel/transclusion rel/transcludes rel/links rel/links-to Jon SterlingKento Okura20241020https://www.forester-notes.org/013D/013D/013D/New built-in relationsA few new built-in relations have been added.rel/is-node ?X is a unary relation that holds for any tree address ?X. This is needed when specifying reflexive binary relations: the clause R ?X ?X -: is not allowed by datalog, so one must use . rel/transcludes/transitive-closure is the transitive closure of rel/transcludes. rel/transcludes/reflexive-transitive-closure is the reflexive transitive closure of rel/transcludes. rel/is-reference ?X holds when ?X is designated as a reference/bibliographical tree. Currently, the built-in rules of the database deduce rel/is-reference ?X for any tree ?X with taxon Reference. The purpose of abstracting from the taxon is to enable non-English users of Forester to benefit from the computation of bibliographies. Similarly, rel/is-person ?X holds when ?X is designated as a personal/biographical tree. Currently, the built-in rules of the database deduce rel/is-reference ?X for any tree ?X with taxon Person. rel/in-bundle-closure ?X ?Y is the reflexive transitive closure of the union of the transclusion relation with the relation of ?X requiring the asset ?Y. The purpose of this relation is to easily bundle up fragments of a forest (see § ).All of these built-in relations can be defined in Forester’s dialect of datalog; they are predefined for convenience, and because they are used in the computation of backmatter.Jon SterlingKento Okura20241020https://www.forester-notes.org/013E/013E/013E/An example datalog queryExampleIn order to illustrate the use of the datalog engine, I will show how to construct a query that will find all the reference trees written by jonmsterling that are tagged either accepted or refereed. The first thing we must do is define the smallest relation containing all trees tagged accepted or refereed; this is done by adding clauses to the database as follows.First we define the name of a relation. In the current release, relations are global strings and there is no facility to generate a “fresh” one; that may change in the future.Next, we add two defining clauses for our relation. In what follows, simply delimits content that should be parsed as a datalog expression, and instructs Forester to execute the datalog expression.The left-hand side of the reversed turnstile -: is a proposition representing the goal; the right hand side is given by propositions representing the premises, each surrounded in braces and separated by whitespace. Metavariables are written with a question mark sigil. Literal content is embedded into a datalog proposition by surrounding it in '{...}; we will see that literal content is one kind of vertex in the graph database.Now that we have actually defined the relation that we will use, we can run a query:The structure of a query identifies the metavariable being solved behind the turnstile, and then lists the clauses that must hold. Whereas a content vertex is addressed via '{...}, a URL vertex is addressed using @{...}.Jon SterlingKento Okura20241020https://www.forester-notes.org/30FO/30FO/30FO/Atom syndication supportIt is now possible to syndicate a given tree as an Atom feed; for example, if you have a tree for your blog and its subtrees/transclusions are your blog posts, you can include the following code to generate an Atom feed for this blog:If your blog is located at https://www.my-great-forest.net/my-blog/, then there will be an atom feed placed at https://www.my-great-forest.net/my-blog/atom.xml.This feature is experimental and has some limitations.Jon SterlingKento Okura20241020https://www.forester-notes.org/30FN/30FN/30FN/Publishing and implanting forestsForester now includes an experimental feature to “publish” a portion of your forest to a JSON blob that can be read by Forester and implanted into another forest. For example, if you include the following code in a tree within your forest, then a file will be emitted at output/my-forest.json containing the compiled content of your entire forest, together with all the assets:Of course, more sophisticated queries can be used. For example, you can emit all the items tagged public together as follows:To implant the resulting JSON file into another forest, simply copy over the file and add the following line to your configuration file:By default, implanted trees will be rendered to your output folder underneath a foreign/ directory; if you wish to instead that links to implanted trees be routed directly to their canonical URLs (which will likely be the case if you implant a public forest), then you may configure that as follows:This feature is highly experimental and has many limitations; it will change in breaking ways in the near future. Although we are very interested to learn about the limitations of this feature, we will be taking a hands-off approach to support until the feature has taken a more stable form.Jon SterlingKento Okura20241020https://www.forester-notes.org/VNQ8/VNQ8/VNQ8/Changes to how forests are viewed locally and deployedIn the past, Forester’s XML output used relative URLs for all links. This was tractable because the output had no directory structure, but this is increasingly becoming problematic—for example, foreign trees are going to be rendered to a subdirectory, but this breaks all the relative URLs. I have come to the conclusion that the only way forward is to use absolute URLs for everything, but this assumes that the output is being served from the root directory of some host. As a result, users must fire up an HTTP server in order to view their forest locally. With this release we will (TODO) include a built-in HTTP server, but early adopters can simply run python3 -m http.server 8000 from the output directory and open localhost:8000 in their browser.Some users may wish to deploy their forest somewhere other than the root directory of a given (sub)domain. To achieve this and have all your links work correctly, enter the following configuration:Jon SterlingKento Okura20241020https://www.forester-notes.org/P9BN/P9BN/P9BN/Changes to handling of assetsAssets in compiled forests are content-addressed by their hash; a new primitive is provided for generating the correct URL of an asset that is stored in a designated assets directory. For example, to embed an image that is stored in assets/images/my-great-illustration.jpg, you would write the following code:[src]{\route-asset{assets/images/my-great-illustration.jpg}}{}]]>Jon SterlingKento Okura20241020https://www.forester-notes.org/0127/0127/0127/The future of Forester’s XML formatForester currently emits archival-quality output in a custom XML format that is then interpreted using an XSLT stylesheet (as part of the “theme”). This format has served us well, enabling users to customise the presentation of their forests to a great degree. An added benefit of the XML format is to be able to easily convert a tree to LaTeX using another stylesheet.However, the constantly changing XML format has been an equally frustrating source of churn for users of Forester, and I have for some time now been warning users who customise their theme that these customisations are technically possible but not supported (i.e. we make no promise not to break them).The time is coming when Forester’s interaction model and output format will be changed drastically; rest assured that the core principles behind Forester (including the ability to generate static archival output that can be hosted anywhere) will be retained. We aim to become a better citizen of the World Wide Web by moving toward a more standard hypermedia format.One possiblity is to extend HTML with just the hypermedia controls and embedded microformats needed for Forester’s operation. This re-coupling of presentation and data would, paradoxically, facilitate Forester to evolve more rapidly over time while simultaneously increasing the longevity of forests that have been compiled using older versions of the tool.Jon SterlingPatrick NicodemusKento OkuraNick HuOwen Lynch2024810https://www.forester-notes.org/0109/0109/0109/Forester 4.3ReleaseThis is a smaller release that contains a few changes to how Forester works under the hood. As usual, you must upgrade your theme submodule to the 4.3.0 tag.Jon SterlingNick Hu2024810https://www.forester-notes.org/010A/010A/010A/Changes to external LaTeX renderingPreviously, the construct would generate a .tex file, convert it to an SVG file, and then copy it into output/resources/; this file would then be referenced in the resulting XML using the <forester:embeddex-tex> element, which was rendered by the theme to <html:img>.Now, the contents of the SVG file are embedded directly into the resulting document as an <html:img> element with a base64-encoded data-url. The <forester:embedded-tex> element is no longer used.The goal of this change is to make the output files more self-contained and less reliant on surrounding files. A downside of the present change is that it makes the output files a bit larger, as base64-encoded SVGs are not exactly small. In the future, we might instead embed the SVG code into the DOM (which could have some benefits for accessibility), but if we do this, we will have to massage the SVG output to remove duplicate @id attributes.Jon SterlingOwen Lynch2024810https://www.forester-notes.org/010B/010B/010B/Static builds for linuxA build-static-linux.sh script has been added which can be used, in connection with Docker, to build a static binary that can be run on Linux.Jon SterlingKento OkuraJinser Kafka2024620https://www.forester-notes.org/00WK/00WK/00WK/Forester 4.2ReleaseThis release brings several internal changes that are meant to facilitate the further improvement of Forester, as well as some user-facing changes (most notably a new query language). These are breaking changes: existing queries will need to be translated, and you will need to upgrade your theme.Jon Sterling2024620https://www.forester-notes.org/00YF/00YF/00YF/First-class functions and lazy argumentsThis release adds λ-abstraction, which can be written like so:In addition, lazy arguments are now supported. In any place that a function argument can be bound (e.g. in , , or ), an argument marked with a tilde is automatically wrapped in a thunk when it is passed. For example, consider the following code:In the above, the argument x is strict and y is a thunk that must be forced before being used—hence the application to {}; note that the results are not memoised. The code above is functionally equivalent to the following:Of course, when your code is pure, passing by name vs. by value does not make a difference. The purpose of this feature is, however, to enable more expressive macros that make use of fluid bindings.Jon Sterling2024620https://www.forester-notes.org/00YG/00YG/00YG/Combining fluid bindings and lazy argumentsExampleForester 4.0’s enhanced XML support makes it possible (see Example ) to write MathML directly as an alternative to using Forester’s TeX-like math mode via KaTeX. For example, we can write the following wrappers for some basic MathML elements:{\body}} \def\mrow[body]{\{\body}} \def\mi[x]{\{\x}} \def\mo[o]{\{\o}} \def\mn[n]{\{\n}}]]>With this in hand, we can write prose involving MathML content, like so:The above is a bit messy. We can clean it up with some function definitions:It is annoying that we have to always wrap things in . By combining first-class functions, lazy arguments, and fluid bindings, we can lift this requirement: element. \def\ensure-math[~body]{% \scope{% % Set a default value for \math-wrapper (no-op if already set). \put?\math-wrapper{\fun[x]{\{\x}}}% % % Apply the current function bound to \math-wrapper. \get\math-wrapper{% % Bind \math-wrapper to the identity function in the current scope so that % we do not get redundant nodes. \put\math-wrapper{\fun[x]{\x}}% % % Force the \body thunk to evaluate the body within the wrapper. \body{}% }% }% }]]>We now re-define our macro library to use the :{\x{}}}} \def\mi[~x]{\ensure-math{\{\x{}}}} \def\mo[~x]{\ensure-math{\{\x{}}}} \def\mn[~x]{\ensure-math{\{\x{}}}} \def\plus[~x][~y]{\mrow{\x{} \mo{+} \y{}}} \def\equals[~x][~y]{\mrow{\x{} \mo{=} \y{}}}]]>Now, we can put MathML content freely into prose without needing to wrap it each time.Jon Sterling2024620https://www.forester-notes.org/00YH/00YH/00YH/Lazy arguments are experimentalWarningPlease note that these features are experimental and subject to change—only build large macro libraries relying on them at your own risk.Jon Sterling2024620https://www.forester-notes.org/00WS/00WS/00WS/New query languageThe existing querying feature, introduced in Forester 2.2, has been replaced by something much better — at the cost of a breaking change that will require existing queries to be rewritten.Jon Sterling2024620https://www.forester-notes.org/00WU/00WU/00WU/New syntax for set operationsIntersections of queries are formed using a variadic constructor . For example, the following computes the intersection of the queries q1, q2, and q3:Unions of queries are formed similarly using the variadic constructor. The complement of a query q is written .Note: as before, to render the results of a query you must use the command; for example:Jon Sterling2024620https://www.forester-notes.org/00WV/00WV/00WV/Query operations are first-class valuesPreviously, the built-in query operations were written like , etc.; these names, however, were hard-coded into the lexer which meant that they did not work in the expected way with Forester’s hierarchical namespacing. This hardcoding has been removed, and query operations are treated as first-class values that are resolved from primitive names in the namespace. As such, the following code is equivalent to :A further consequence of this change is that queries can be defined compositionally by macros.Jon Sterling2024620https://www.forester-notes.org/00WW/00WW/00WW/Relational queriesThe most significant user-facing change to the query language is the ability to form basic relational queries along several built-in relation-symbols; in fact, the built-in query constructors , , and are all expressible in these terms.Jon Sterling2024620https://www.forester-notes.org/00WX/00WX/00WX/Built-in relation symbolsForester includes several built-in relation symbols, maintained as graphs that are accumulated during evaluation: contains an edge from x to y when x directly transcludes y, i.e. contains . contains an edge from x to y when x links to y, i.e. contains something like or . contains an edge from x to y when x has taxon y, i.e. contains . contains an edge from x to y when x has tag y, i.e. contains . contains an edge from x to y when x has author y, i.e. contains . contains an edge from x to y when x is a tree with contributor y, i.e. contains .The implementation supports arbitrarily many relation symbols; this is not yet exposed to the user, but could in the future be employed by advanced users of Forester to support the development of sophisticated ontologies.Jon Sterling2024620https://www.forester-notes.org/00WZ/00WZ/00WZ/Query modes and polaritiesGiven an address x and a relation symbol r, there are several useful queries that we might wish to make:We might wish to find all incoming edges to x in r, or we may wish to find all outgoing edges from x in r. We shall refer to the differenec between incoming and outgoing edges is referred to as a polarity. Rather than searching for edges, we may wish to search for paths — which corresponds to passing from a relation to its preorder reflection. We will refer to this distinction as a mode.Forester supports both polarities and modes for relational queries via the following built-in constants: and denote the two polarities. and represent the two modes.Jon Sterling2024620https://www.forester-notes.org/00WY/00WY/00WY/The syntax of a relational queryA relational query takes the following form:In the above, mode and polarity must evaluate to mode and polarity constants as in § ; relation must evaluate to a relation symbol as in § .Jon Sterling2024620https://www.forester-notes.org/00X0/00X0/00X0/Expressing built-in queriesExampleThe built-in basic queries can be expressed in terms of in the following way:Jon Sterling2024620https://www.forester-notes.org/00X2/00X2/00X2/Querying the (back)links and context a given treeExampleBoth the backlinks and (forward) links of a given tree can be computed using a query to the relation, and the context (immediate parents) of a given tree can be obatined from the relation:Jon Sterling2024620https://www.forester-notes.org/00X4/00X4/00X4/Querying a coslice of the transclusion preorderExampleWe can also write a query to compute the set of trees underneath a given tree in the transclusion preorder (including the original tree) — in other words, the coslice.Jon Sterling2024620https://www.forester-notes.org/00X1/00X1/00X1/Unions and intersections of families of queriesA further primitive query-former is the union or intersection of a certain family of queries indexed in the results of a fixed query. These are written as follows:In the above, q is a query expression and qfam is a first-class function that takes an address and returns a query expression. There are a couple built-in instantiations of and for the specific case where qfam is a family of relational queries; for example:is equivalent to the following more verbose code:Jon Sterling2024620https://www.forester-notes.org/00X3/00X3/00X3/Querying the bibliography of a given treeExampleWe can define a macro to compute the bibliography of a given tree, making use of from Example .The above code first accumulates all the outgoing links from the given tree and any of its children, and then restricts (by intersection) to those with taxon reference.Jon Sterling2024620https://www.forester-notes.org/00X5/00X5/00X5/Querying all hereditary contributors to a treeExampleWe can use the union of families of relational queries to compute the set of (proper) contributors to a given tree. This is slightly subtle, because if a bibliographic tree is transcluded, we do not want its contributors to be included.In the future, the support for query-indexed families of queries might be generalised to allow arbitrary queries in the components rather than only relational ones. The current version of the feature should be viewed as somewhat provisional.Jon Sterling2024620https://www.forester-notes.org/00WT/00WT/00WT/Queries are experimentalWarningIt is strongly recommended that inexperienced users of Forester continue to limit their usage of queries until the feature has reached a stable interface.Jon Sterling2024620https://www.forester-notes.org/00WL/00WL/00WL/Intermediate representation of the XML formatForester’s primary output format is XML, rendered live in the browser to HTML using an XSLT stylesheet. Although this will continue to be the main output format, together with Kento Okura as well as our friends from the Topos Institute I am hoping to explore richer hypermedia interfaces for forests that could transcend the limitations of static HTML output.In order to support multiple backends without creating a log of code churn, I have created an OCaml abstraction of the XML format that will serve as a “source of truth” for Forester’s output — which can be serialised directly to XML, or rendered in a different way (e.g. as HTML or htmx emitted by a hypermedia server).With this change, I would expect Forester’s XML format to begin to change less and less over time, perhaps culminating in a versioned schema. I do not, however, guarantee that I will not make breaking changes to the format going forward.Jon Sterling2024620https://www.forester-notes.org/00WM/00WM/00WM/Generalised backmatterCurrently, the backmatter of a tree is not customisable; although the default backmatter sections are useful for most trees, it is likely that some of the sections are less relevant at times, and that other kinds of queries would be useful to be able to include on a tree-by-tree basis.In order to facilitate such a feature in the future, this release changes the representation of backmatter to support arbitrary content and queries. This is a breaking change to the XML format: the <backmatter> element now contains arbitrary <tree> elements that encode the backmatter sections. By virtue of the improved query engine, all default backmatter sections are computed from queries.Jon Sterling2024620https://www.forester-notes.org/00WN/00WN/00WN/HTML figures and captions; embedded TeXThis release adds figure and figcaption primitives that are interpreted by the XSLT stylesheet as HTML’s <figure> and <figcaption> elements.The stylesheet no longer emits the images corresponding to embedded inside a <center> tag, as this is deprecated in HTML. Users are encouraged to wrap Forester’s tex primitive in a macro that embeds a diagram in a figure. For example, the following code comes from my own macro preamble:Jon Sterling2024620https://www.forester-notes.org/00ZF/00ZF/00ZF/Performance improvements in graph analysisThe previous graph implementation has been replaced with one that is more time-efficient (at the cost of space). Computing the transclusion preorder (or, more generally, the reflexive-transitive closure of relations) is orders of magnitude faster; my own forest ultimately compiles in twice the speed.Jon SterlingKento OkuraTrebor HuangNick Hu2024615https://www.forester-notes.org/00S9/00S9/00S9/Forester 4.1ReleaseSpecial thanks to Kento Okura, Nick Hu, and Trebor Huang for their contributions to this release.Jon SterlingKento Okura2024615https://www.forester-notes.org/00U0/00U0/00U0/New forester init commandTo make it easier to set up a new forest, we have added a forester init command; when you run this command in an empty directory, it will initialise a git repository with a submodule for the default theme pinned to the correct release, and a configuration file.Jon Sterling2024615https://www.forester-notes.org/00WA/00WA/00WA/Rendering only a subset of the forestA new option has been added to the forester build command to render only certain trees. For example, the following command will render only the trees at addresses xxx-MMMM and yyy-NNNN:forester build forest.toml --render-only=xxx-MMMM,yyy-NNNNNote that in order to maintain a correct graph analysis, the entire forest will nonetheless be evaluated. As rendering is the slowest part of the process, however, this option can still save a lot of time. In the future it could be useful to have a more sophisticated option that renders (e.g.) all children of a given tree, etc.Jon Sterling2024615https://www.forester-notes.org/00SP/00SP/00SP/Changed behaviour of queriesForester’s rudimentary support for queries has been simplified somewhat. Previously, the results of a query would be gathered and, if non-empty, placed underneath an anonymous subtree (whose title could be modified using transclusion options).In light of the user-level support for anonymous subtrees introduced in Forester 3.1, the behaviour of queries has been simplified: the results of a query are simply transcluded directly without being enclosed in a subtree.Although the new behaviour is simpler, it is no longer possible to have a query subtree that is hidden when it returns no results. Users should treat the querying feature as highly provisional, and subject to change and even potential removal.Jon Sterling2024615https://www.forester-notes.org/00SQ/00SQ/00SQ/Addresses for anonymous treesPreviously, a subtree could be emitted without any address; this greatly complicated the logic of the graph analysis, designated parents, and other things. Now, emitting an anonymous subtree generates a fresh address in a separate namespace; as a result, these trees get rendered to their own XML file. Naturally, an anonymous subtree cannot be linked to or transcluded, but it can now participate properly in the graph analysis.Jon SterlingNick Hu2024615https://www.forester-notes.org/00SA/00SA/00SA/Incremental parsingMenhir’s incremental parsing API is adopted in order to make the parser more resiliant to syntax errors. The goal is to support language server protocol diagnostics in a future release.Jon Sterling2024615https://www.forester-notes.org/00WG/00WG/00WG/Dependency auditIn recent releases, Forester has become increasingly dependent on various system packages (including openssl) via transitive dependencies. This has caused a great deal of build breakage for both our developers and users, so we decided to remove all but the most critical dependencies to avoid losing control of things. Experimental tools that rely on more system dependencies that are likely to cause build breakage can be created, but only outside the main forester package.Jon SterlingKento Okura202445https://www.forester-notes.org/00RF/00RF/00RF/Forester 4.0ReleaseThis is a major release of Forester that changes both the command line interface and the XML format, introducing many new features under the hood as well as quality-of-life improvements (including a 2X rendering speedup).Jon SterlingKento Okura202445https://www.forester-notes.org/00RG/00RG/00RG/Forest configuration via TOMLPreviously, the locations of trees as well as assets and theme directories were configured by means of command line arguments. As this has become a bit unwieldy, especially as many users have multiple projections of their forest, we have consolidated these options under a simple TOML configuration file whose location is the first argument to most forester commands. Here is an example configuration file:It is common to have multiple configurations. For example, if you have “public” trees located in a specific directory, you can have an additional configuration:Both the assets and theme keys are displayed above with their default values, so they could be omitted. There is an additional stylesheet key that can be used to set the name of the XSL stylesheet used (the default is forest.xsl).To build the forest, simply run: forester build forest.toml; other options can be used (see forester build --help), such as forester build forest.toml --dev.Jon Sterling202445https://www.forester-notes.org/00RH/00RH/00RH/Enhanced XML supportJon Sterling202445https://www.forester-notes.org/00RI/00RI/00RI/An XML namespace for ForesterThe XML format is now governed by the XML namespace with URI http://www.jonmsterling.com/005P.xml; as is typical of XML grammars, element names are namespaced whereas attribute names lie in no namespace. Forester emits XML with element names qualified by a prefix bound to this namespace. This change breaks existing XSL stylesheets, so you must upgrade your theme.The new version of the default theme contains rules to allow anything in either the http://www.w3.org/1999/xhtml or http://www.w3.org/1998/Math/MathML namespaces to be copied through to the output HTML (with namespace prefixes stripped). In combination with § , this allows you to write HTML and MathML in Forester directly.Please note that although Forester now has a namespace, it does not has a schema. Any direct integration with the XML format (e.g. by custom themes) is not supported and should be done at your own risk — several recent releases have illustrated the continued rapid evolution of the XML format with many breaking changes. I expect this evolution will continue for some time.Jon Sterling202445https://www.forester-notes.org/00RJ/00RJ/00RJ/Emitting XML and resolving namespacesSince version 3.0, Forester’s source language has supported a limited form of custom XML output by means of the command. This support was, however, somewhat unwieldy: no built-in accounting for XML namespaces was included, so correct usage of was prohibitively difficult because of the need for xmlns attributes on essentially every node.Jon Sterling202445https://www.forester-notes.org/00RK/00RK/00RK/XML namespace declarationFeatureForester treats XML namespace prefixes in a way that respects -equivalence: in other words, any prefix mentioned must be bound, and it is possible for two different textually identical namespace prefixes to denote different namespaces depending on their scope. This makes it possible to compose code that emits XML without coordinating namespace prefixes, which I have found to be a major impediment to the correct use of XML for non-trivial work.An XML namespace prefix is bound by a declaration like the following:This declaration has the same scoping rules as .Jon Sterling202445https://www.forester-notes.org/00RM/00RM/00RM/XML literalsFeatureThe old syntax has been replaced with a new convenient notation for XML literals that supports declared XML namespace prefixes. The grammar of XML literals is summarised below:[qname]{expr}...{expr}]]>For example, if the prefix html: is bound to http://www.w3.org/1999/xhtml as in Feature , the expression [class]{highlight}{some highlighted text}]]> will emit the following XML: some highlighted text ]]>In reality, the appropriate @xmlns:html attribute will be attached only where it is needed in keeping with the hierarchical structure of the XML tree. Note that when the same textual prefix is bound to two different namespaces, one of them will be automatically -renamed so as to result in correct XML with the intended semantics.Jon Sterling202445https://www.forester-notes.org/00RL/00RL/00RL/A worked exampleExampleThe following code causes MathML to be emitted (in the correct namespace), combining Feature and Feature :[display]{block}{ \{ \{ \{x} \{2} } \{+} \{x} } }]]>The above displays as follows: x 2 + x Jon SterlingKento OkuraOwen Lynch202439https://www.forester-notes.org/00HY/00HY/00HY/Forester 3.1ReleaseTo use this release, you will need to upgrade your theme and you may also need to edit your forest itself (please write to the mailing list if you encounter difficulties). Remember that this includes not only the XSLT stylesheet, but also the CSS stylesheet and the JavaScripts.The base theme is now versioned: if you are using Forester 3.1, you can confidently use the 3.1.0 tag. The head of the main branch of the theme may at times include changes that are compatible with only the main branch of Forester itself.Jon Sterling202439202428https://www.forester-notes.org/00O3/00O3/00O3/Designated parentsFeatureIn keeping with the philosophy of evergreen notes, hierarchical structure in Forester has always been introduced by transclusion of independent trees; in this model, a tree has no canonical parent because it may be contextualised in many distinct hierarchical narratives. Experience using Forester suggests that this is the right idea the vast majority of the time, but use-cases have emerged that challenge these assumptions: there do indeed arise natural subtrees that are exceedingly awkward to “decontextualise”.For example, the features described in a changelog (such as the present one) are awkward to decontextualise because they refer to knowledge that is temporary in its applicability. Likewise, the subtrees of one’s daily notes or journal are likely to be fleeting in nature and may have little insight that can be decontextualised — and in spite of this, these notes remain important for restoring mental context on long-running projects, etc.For these reasons, I have (reluctantly) added a new frontmatter directive , which designates the tree at address xxx-NNNN as “the” context-providing parent of the current tree. This feature is experimental and under-theorised; it should be used sparingly.When a given tree appears transcluded within its “designated” parent, it will be shown with the title that has been specified; however, when the tree appears outside of this context, its title will appear with the parent’s title prepended to it: “parent › child”.Jon Sterling202439202428https://www.forester-notes.org/00O4/00O4/00O4/Inline subtreesFeaturePreviously, there was a one-to-one mapping between trees and files. After discussion on the mailing list with Kristopher Brown, I have added support for defining new subtrees inline to an existing tree. The current behavior is that an inline subtree has its designated parent automatically assigned; author and date metadata is inherited (this may change in the future).To emit (and transclude) a subtree at address xxx-NNNN, you can write the following:It is also possible to have an anonymous inline subtree, one that has no address of its own. In this case, write:An anonymous inline subtree will, naturally, not have its own page emitted and cannot be linked to. In the graph analysis (for computing backlinks, etc.), an anonymous inline subtree will be identified with its parent.Inline subtrees should not be overrused; but they may make the process of daily journalling and other activities more lightweight.One consequence of breaking the one-to-one relationship between trees and files is that commands like forester new need to actually fully evaluate the forest, whereas in the past it was possible to merely scan the file system. This is a trade-off: if your forest contains fatal errors, you cannot use forester new or related querying commands. You should never leave your forest with fatal errors long enough to notice this.This feature is experimental and its behaviour may change. Use it at your own risk.Jon Sterling2024112https://www.forester-notes.org/00HZ/00HZ/00HZ/cleveref-style referencingFeatureYou can now write to produce a link to the tree at address xxx-NNNN labeled by its taxon. After the taxon, the textual format and destination of the link depends on whether xxx-NNNN lies in the present context. If the linked tree is present, then link will refer to the first transclusion of the tree into the present context; otherwise, the link will refer to the tree’s stable address. For example:A reference to this very tree: Feature . A reference to a parent of this tree: Release . A reference to a cousin of this tree: Feature .The behavior of references within one tree naturally depends on the transclusion context in which you are viewing that tree. It is instructive to examine the examples above by viewing this tree from its parent or on its own page.Jon SterlingKento Okura202439https://www.forester-notes.org/00O5/00O5/00O5/New forester query commandFeatureKento Okura has implemented a new forester query command that may be useful for creating external editor tooling; currently it is possible to query for lists of all prefixes (the xxx in xxx-NNNN), tags, and taxa. Please run forester query --help for more information.Jon SterlingOwen Lynch202439https://www.forester-notes.org/00O6/00O6/00O6/Random vs. sequential generation of addressesFeatureBy default, Forester generates tree addresses sequentially within a given prefix; Owen Lynch has implemented forester new --random, which instead generates random tree identifiers. Although this option is not recommended for most users, it can be used to mitigate the problem of multiple collaborators creating trees within the same prefix. Please run forester new --help for more information.Jon Sterling202439https://www.forester-notes.org/00Q6/00Q6/00Q6/Manual numbering for digital editionsFeatureNumbering of trees in Forester is by default relative and determined by position in the current view. When creating translations or digital editions, the numbering from the source material is what is important. For this reason, I have added a new frontmatter directive to impose a manual numbering on a given tree.This numbering will be used in the table of contents, headings, and by Feature .Jon Sterling202439https://www.forester-notes.org/00OH/00OH/00OH/Improvements to verbatim lexerChangeForester includes a special lexing mode for quoting source code, delimited by startverb and stopverb. This mode was never implemented properly and so it did not work well in practice; for example, previously the line comment lexer could be activated via from within vebatim mode, which made it very difficult to quote code that has comments. The lexer has been revamped and the behavior of verbatim mode is a bit different from before.Between the delimiters (startverb,stopverb), text now is taken precisely as-written, except that newlines are stripped from the beginning and the end of the quoted text. Previously, the strange behavior of comments noted above could be used to manually avoid an initial line break from appearing in the quoted text. So in a prior version of Forester, you may have written something like this:Now, you should instead write:Jon Sterling2024125https://www.forester-notes.org/00LR/00LR/00LR/Removal of and changes to ChangeIn Forester 2.1, the frontmatter command was added in order to accumulate a list of packages that are then used automatically when rendering . From Forester 3.1, this feature is removed and to embed code, you must explicitly specify the preamble as follows:Of course, within a single project (or even forest), you may have a relatively stable set of packages that you need. In this case, it is recommended to wrap in your own macro:An even more sophisticated approach might use fluid bindings to allow local customisation of packages in use:Jon Sterling202439202428https://www.forester-notes.org/00O2/00O2/00O2/Removal of undocumented outputChangePreviously, Forester would emit .tex files for each of your trees in the latex directory. This feature has been removed, as can be generated more reliably using XSLT. Please see the forester-to-latex repository for an example stylesheet.Jon Sterling2024125https://www.forester-notes.org/00LS/00LS/00LS/Breaking changes to the XML formatChangeForester 3.1 makes some breaking changes to the XML format; if you are using the default theme, just update it to the latest version to migrate your forest. The main change is that “trails” for subtrees (like “1.4.2”) are no longer computed ahead of time and stored in XML, but are instead computed on the fly in the XSLT stylesheet using <xsl:number>.A further change is that embedded is no longer emitted using the <img> element: instead, there is a new <embedded-tex> element with an attribute @hash containing the name (without extension) of the appropriate SVG file, and with children elements <embedded-tex-preamble> and <embedded-tex-body>. These are meant to facilitate generation of documents from Forester’s XML output in combination with the filecontents environment.Jon SterlingKento OkuraLîm Tsú-thuànOwen LynchKuen-Bang Hou (Favonia)2023113https://www.forester-notes.org/00CW/00CW/00CW/Forester 3.0ReleaseThis is a major breaking release; some surgery may be required on existing forests. Thanks to Favonia, Kento Okura, Lîm Tsú-thuàn, and Owen Lynch for their contributions to this release. Thanks also to Adrien Guatto for bug reports.Jon Sterling2023113https://www.forester-notes.org/00CX/00CX/00CX/Proper diagnostics with source locationsFeatureForester 3.0 adds proper diagnostics and error messages, via the excellent asai library maintained by Favonia. When something goes wrong in your forest, the terminal output should expain what happened while displaying the precise location in your source file.Jon Sterling20231119https://www.forester-notes.org/00EY/00EY/00EY/Experimental support for objectsFeatureTo facilitate the development of extensible macro libraries for diagramming and other tasks, Forester 3.0 introduces experimental support for objects — which should be thought of as combination of records/structs, closures, and general recursion. An object is created like so:The variable self is explicitly bound, and can be bound to any name you like. Methods currently are not allowed to take any arguments, but this may change in the future. A primitive form of inheritance is supported, using :The support for objects in Forester 3.0 is extremely experimental and preliminary: users are discouraged from relying on it.Jon Sterling20231120https://www.forester-notes.org/00F0/00F0/00F0/Improvements to date handlingFeatureForester 3.0 improves support for journaling with date-specific trees. When a tree is dated YYYY-MM-DD and there exists a tree at address YYYY-MM-DD, the date field will be hyperlinked to the latter. This involves changes to both the executable and the XSL stylesheet of the base theme. The purpose of this change is to better facilitate daily notes / journaling.Additionally, Forester’s data model now allows multiple dates to be assigned to a single tree simultaneously.Kento Okura20231122https://www.forester-notes.org/00FI/00FI/00FI/Nix supportFeatureForester 3.0 comes with a nix flake for easy integration with nix-based systems. Users of nix can try forester without installing the ocaml toolchain by running nix run sourcehut:~jonsterling/ocaml-forester.To create a development shell with forester and LaTeX dependencies, create a file named flake.nix with the following content:and run nix develop.The default template now ships with a flake and an envrc. If you created your forest using this template and would like to use direnv, simply copy flake.nix and .envrc to your forest base directory.Jon SterlingLîm Tsú-thuàn2023122https://www.forester-notes.org/00G7/00G7/00G7/Lightweight templating in forester newFeatureForester 3.0 adds a new --template option to the forester new command. Running forester new --template xxx-0001 will create a new tree with the contents of the existing tree xxx-0001.Jon SterlingOwen Lynch20231213https://www.forester-notes.org/00GG/00GG/00GG/Support for randomised tree identifiers in forester newFeatureThe forester new has a new --random flag; when activated, the new tree will be allocated with a randomised unused tree identifier rather than the usual sequential tree identifier. This can be useful for projects that have multiple collaborators, although in this case, users are generally advised to claim their own namespaces.Jon Sterling20231215https://www.forester-notes.org/00GL/00GL/00GL/Custom static assets directoriesFeatureA new --assets-dirs option has been added to the forester build command, which can be used to supply multiple directories containing static assets that should be copied into the forest. By default, the option is set to assets.Jon Sterling2023113https://www.forester-notes.org/00CY/00CY/00CY/Breaking changesForester 3.0 introduces a number of breaking changes to the source language in order to facilitate maintainability, diagnostic support, and extensibility of both the Forester tool and your individual forests.Jon Sterling2023113https://www.forester-notes.org/00CZ/00CZ/00CZ/Fall-through of undefined identifiersChangeThe fall-through for undefined identifiers in XML mode is removed in Forester 3.0: previously when an identifier was undefined, it was possible to write and have this be rendered in XML to body]]>.This behavior has been removed, but you can nonetheless write to achieve the same. For content that is being rendered by either LaTeX or KaTeX, simple fallthrough (naturally without attributes or arguments) is supported; therefore will render to .Jon Sterling2023113https://www.forester-notes.org/00D0/00D0/00D0/Primitive formatting commandsChangeAs a consequence of the changed fallthrough behavior, several new primitives have been added to the source language, including , , , , , , , and .You can add further commands to your primitives using a combination of , , and .Jon Sterling2023927https://www.forester-notes.org/009Q/009Q/009Q/Forester 2.5ReleaseThanks to Lîm Tsú-thuàn and Vikraman Choudhury for their suggestions and bug reports on the mailing list.Jon Sterling2023927https://www.forester-notes.org/UM95/UM95/UM95/New commandA new command has been added, following a suggestion of Vikraman Choudhury; this can be used to control the behavior of macros, depending on whether they are being rendered by or by the browser. For example, will become foo when passed to the tool, but will be reated as bar when rendering for the browser.Jon Sterling2023927https://www.forester-notes.org/UMS4/UMS4/UMS4/Overriding taxaA new fluid binding has been added to the transclusion overrides, which can be used to locally change the taxon of a transcluded tree. Thanks to Lîm Tsú-thuàn for implementing this.Jon Sterling2023927https://www.forester-notes.org/NRTU/NRTU/NRTU/Theme and asset directoriesIn order to support more modular development of forests, a new theme directory is expected to contain all the XSL, CSS, font, etc. assets that pertain to the presentation of your forest; the assets directory is meant to store things like images, PDFs, etc. that pertain to the content of your forest. The simplest way to take advantage of this new feature is to bind your theme directory to a git submodule pointing to the forester-base-theme repository. Your existing forest will still work fine for now even if you do not migrate to the new directory structure. I’m grateful to Armaël Guéneau for conversations that motivated me to make this change.Jon Sterling2023922https://www.forester-notes.org/007M/007M/007M/Forester 2.4ReleaseThanks to Masanori Ogino and Harold Carr for their suggestions which have influenced this release. In addition to the major changes detailed below, there are a few minor improvements:The evaluator for Markdown-style links now allows destination to contain expressions other than text, so long as they evaluate to text. The XML attribute support introduced in Forester 2.3 has been amended so that attributes appear in square brackets, e.g. The forester new command now has a --dest option, which is used to specify the directory in which to deposit the new tree (independently of the --dir option, which specifies the directory to scan for existing trees). Please run forester new --help for details.Jon Sterling2023819https://www.forester-notes.org/007Y/007Y/007Y/Rudimentary support for RSS feedsFeatureEach tree generates an RSS feed containing its immediate children; if a tree is located at xxx-NNNN.xml, then the corresponding RSS file will be located at xxx-NNNN.rss.xml. Currently no content is placed in the RSS feed items, but in the future we may add some best-effort plain text linearization of the first paragraph of the tree or something. Feedback on this feature is welcome.Jon Sterling2023913https://www.forester-notes.org/008Z/008Z/008Z/Wikilinks supportFeatureThis release adds support for “wikilinks” in the form ; this will be rendered as a link whose title is given by the title of the tree at address destination. Users are discouraged from using wikilinks heavily, as it is better for your mind to “work a link into a sentence” naturally; but this can be very useful for linking to biographical trees or daily notes.Jon Sterling2023819https://www.forester-notes.org/007X/007X/007X/Breaking changes to XML formatChangeThis release contains several breaking changes to the XML format that can break custom XSLT stylesheets.Taxa used to be attributes of tree, but they are now child elements of tree/frontmatter. Therefore, what previously was written as <tree taxon="lemma"> <frontmatter> <!-- ... --> </frontmatter> <!-- ... --> </tree> is now written as follows: <tree> <frontmatter> <taxon>lemma</taxon> <!-- ... --> </frontmatter> <!-- ... --> </tree> Dates are now stored in machine-readable format. For example, what used to be written <date>August 16, 2023</date> is now written as follows: <date> <year>2023</year> <month>8</month> <day>16</day> </date> It is the responsibility of the XSLT stylesheet to format dates appropriately. Thanks to Masanori Ogino for suggesting this change. All identifiers in the XML format have been regularized to use snake-case; for instance, sourcePath is now source-path and show_heading is now show-heading.Jon SterlingArmaël GuéneauRiley Shahar2023814https://www.forester-notes.org/006Z/006Z/006Z/Forester 2.3ReleaseArmaël Guéneau, Riley Shahar, and Jon Sterling contributed code to this major release. Thanks also to Masanori Ogino for feature requests that made it into this release.This release adds some new features to the command line interface. The original behavior of the forester command is now obtained by calling forester build. Please browse forester --help for more information.Jon Sterling2023814https://www.forester-notes.org/0070/0070/0070/Create new trees from the command lineFeatureA new command has been added in Forester 2.3 to simplify the creation of new trees with the correct base-36 identifier. If your personal namespace prefix is xxx, you may run the following command to create a new tree in the trees directory:If the last tree in this directory was xxx-0039, a new tree will be generated at xxx-003A. The new tree will be populated with a correct declaration.Jon Sterling2023814https://www.forester-notes.org/0071/0071/0071/Tree title completion for tool supportFeatureA new forester complete command has been added to search for trees by their title; the purpose of this command is to facilitate external tool support, such as this proof-of-concept completion engine for neovim. Please browse forester complete --help for more information about this command.Current limitations: the command is currently case sensitive and only searches prefixes; in the future, it would be desirable to support more flexible fuzzy-search.Thanks to Riley Shahar for implementing this feature.Jon Sterling2023814https://www.forester-notes.org/0072/0072/0072/Rudimentary support for XML attributesFeatureWhen Forester encounters an undefined function, it automatically passes through to the XML output. For instance, if the function is not defined, then the Forester code will render to the XML code hello]]>. The Forester 2.3 extends this fall-through behavior to support XML attributes.In particular, if you write , Forester will render the following XML code: hello ]]>Thanks to Masanori Ogino for suggesting this feature, and welcome to the Forester community!.In addition to the major changes above, the following minor changes are included in this release:A title attribute attribute has been added to the XML output of internal links, in order to facilitate tooltips and other affordances in rendered forests. Thanks to Armaël Guéneau for implementing this feature. Subdirectories of input directories will now be traversed automatically; note that the tree address model remains flat, and subdirectories are present only for convenience. Added a nicer command line interface with --help documentation. I have migrated much of the system code to use the experimental Eio library for improved portability. The example forest has been removed from the main repository, and moved into a separate template repository.Jon Sterling2023717https://www.forester-notes.org/005V/005V/005V/Forester 2.2ReleaseJon Sterling2023720https://www.forester-notes.org/0067/0067/0067/Flexible transclusion optionsFeatureThis release replaces the old , commands with a more flexible transclusion configuration mechanism using the support for fluid binding introduced in Forester 2.1. A basic transclusion with the default options is done in the same way as before:The behavior of transclusion is, however, configurable by several globally allocated fluid bindings as depicted in the table below.Jon Sterlinghttps://www.forester-notes.org/0069/0069/0069/Transclusion optionsTable Fluid Binding Default Meaning title (none) To override the tree's title during transclusion. toc true Show the tree in the table of contents. expanded true Whether the tree is expanded or not. heading true If set to false, the tree's contents will be inlined. metadata false Show in a tree's heading. numbered true Whether the tree is displayed with a number or not, transitively on subtrees. It is possible to achieve undesirable results by combining these options in undesirable ways; it is up to you to use them correctly.Jon Sterling2023720https://www.forester-notes.org/0068/0068/0068/A configured transclusionExampleThe following code produces an unnumbered transclusion that nonetheless appears in the table of context, with an overridden title.Jon Sterling2023720https://www.forester-notes.org/0066/0066/0066/QueriesFeatureThis release adds support for generating subsections from transclusions obtained by a query the forest; this can be used to produce topical bibliographies.Jon Sterling2023720https://www.forester-notes.org/006A/006A/006A/A conjunctive query nodeExampleThe following code will generate a subsection containing my “featured talks” as collapsed subtrees:Under the hood, a query node is an “anonymous transclusion” and can therefore be configured using the same options as other transclusions.A minor change is that the assets directly does not need to be flat anymore.As always, existing forests can be upgraded by copying forest.xsl and style.css into their assets directory. Jon Sterling202361https://www.forester-notes.org/005O/005O/005O/Forester 2.1ReleaseThis is a major release that breaks compatibility of the XML format for trees; existing forests can be upgraded by copying forest.xsl and style.css into their assets directory.Development mode and edit button. A --dev option has been added to the forester executable; when this option is enabled, absolute paths will be embedded into tree metadata and an edit button is added to the top of the command palette. Your own TeX preamble. There is no longer a hardcoded LaTeX preamble used for compiling graphics; instead, you can store your own .sty files in the assets directory and import them locally in a specific tree using the new frontmatter command. Fluid binding constructs. Macros in the Forester language have functional semantics, which means that they capture their environment at the time of definition; this differs from the stacks of dynamic scopes that are familiar from the TeX model. This release adds support for fluid bindings via in order to simulate this behavior of TeX where desired; a scope can be delimited using . This can be useful for providing flexible configurations to macros. Tables of contents. Tables of contents are now rendered by the default forest.xsl stylesheet. LaTeX output. LaTeX output with full bibliography support is now available; this feature is still experimental, and may not work properly with some constructs (e.g. code blocks, etc.). Name resolution. The behavior of name resolution was highly erratic in the prior release, and this has been corrected by adopting the yuujinchou library. This change may break trees that depended on the prior behavior. Namespaces and hierarchical identifiers. Identifiers in the Forester language are now hierarchical, with components delimited by /. Namespaces can be created using , outside which all exported identifiers are prefixed by foo/. Namespaces can be opened into the current scope using . Contributions