Core design constraints and guiding principles

Two things to guide the design/development of this project:

• Core constraints . These are things that must be satisfied by the final output, and can help in narrowing the space of possibilities to focus on the most-impactful product.
• Guiding principles. These are general approaches to take when trying to decide between multiple options. They aren't hard rules but heuristics to follow.

Core constraints

The following are as documented in the proposal.

• Support content that is stored in text-based format as well as in ipynb format.
  • text and ipynb files are mirrored
  • text format is accessible
• Generate the following output from one set of source files:
  • a website
  • executable notebooks
  • PDF up to LaTeX standard
• Support numbered equations/thms/figures/tables/sections and document-wide cross-references to all
• Support citations and bib
• Support LaTeX style frontmatter/backmatter (toc, index)
• Integrated testing of embedded code
• Support polyglot content.

Guiding principles

• Support casual users equally to power users. Complicating the feature space to support a "power user feature" should be done with great care.
• Don't try to do everything with this tool. It should be about reducing what's possible and focusing it on publishing documents.
  • Expand the user-facing API or the total feature set of the tool with great care. (as an example, nbconvert is under-utilized because it is too complex to use and maintain)
• Where there are markdown syntax or structure standards, use those, don't create a new markdown standard.
  • If any new syntax or standard is introduced (e.g. if we really do want to create a custom text-based version of notebooks that deviates from tools people already use, this should be done as a broader effort w/ the Jupyter community)
• Where there is pre-existing tech, use that, don't create new tech.
  • Decisions to build new tech should be done after a review of other options as well as pros/cons of each.
• Design for a future with volunteer or under-resourced developers. The technology should be easy for motivated newcomers to read, understand, and modify/improve. This might mean not making the "technically best solution" so that we can take an approach that is simpler to wrap one's head around.
• Minimize the total number of lines of code we need to maintain.
• Users should not need to know anything about the underlying build system that is used. They should be able to use this tool without ever hearing of "Sphinx" or "Hugo" etc. It should "just work" with their content files, a configuration file, and a command-line tool.