ZAP 001 - Page titles¶
12-16 min read · 2,432 words · View in Zensical Spark
This proposal aims to define how we can make the concept of "page titles" inherited from MkDocs less ambiguous in Zensical. It specifies where page titles can be defined in a project, where they are used, and how they are transformed for each use. This is important preliminary work for future proposals on topics such API Docs, versioning, internationalization, and variants.
Problem statement¶
There are currently multiple concepts of a "page title" with poor separation between them. We can distinguish their usage in the output reasonably clearly. There is, typically, a "page title" in the content area of a page, in the form of an HTML <h1> element at the top of the page. A "page title" also appears in the sidebar navigation and the HTML <head><title> element, which is used by the web browser to label the window or tab the page is loaded in.
The term "page title" (or just "title") can refer to any of these uses. In addition to this, there are different ways of defining a page title and complex relationships between these definitions and the usage of a page title. There is a clear need to clarify and, if possible, simplify matters.
What is more, we are looking to make navigation more modular. This means that there will no longer be a 1:1 relationship between a navigation item and a page. Pages will appear in multiple navigation contexts and it will be possible to use different titles in each. Depending on the context, you may want to render a rich version of a page title with some or all markup, or a plain text version. You may want to use shortened versions of the title or the full version that also appears in the content area.
Purpose¶
The purpose of this proposal is to provide clear definitions of the different concepts currently rolled into the notion of a "page title", allowing us to clearly refer to different definitions, uses, and transformations.
A further aim is to define the degrees of freedom that authors need - without jumping ahead and specifying a concrete solution at this point.
Access to full proposals requires a Zensical Spark membership
The content shown here is an excerpt from the full proposal. To view the complete proposal, provide feedback, and ensure alignment with your organization's needs, a Zensical Spark membership is required.