mdtools 2.x:

see ./proposal-for-mdtools-2.0.md for details (mostly outdated now...)

Order of user stories is relevant for handling dependencies!

This update will most likely break the deckset renderer and the reveal.js renderer pretty thoroughly.

- first page and (page title in title tag of that link) is hardcoded in html-head.html, that should be a config variable and an entry in the translation memory

- make sure texts for prev/next are added to translation memory

- bug: images zoom under menu

- bug: zoomify/css: icons are not possible in index.html (or anywhere else in the content)

- menu is not 100% wide on mobile

- break in navigation buttons on mobile

- fix vertical spacing in the text

- fix gitHub page:

- all assets must must prepend baseurl (e.g. "/mdtools"): like so: {{ "/assets/style.css" | relative_url }} @done(22-02-24)

- all links must know baseurl??? -> this must remain broken for now, because that means adding code in several places, and figuring out a way to handle local preview and publishing, maybe di that together with redirect and page structure that reflects the content structure?

- section links could be lowercased before rendering???

- check out how Javascript Tutorial handles translations of illustrations, they solve the exact same problem we do

https://github.com/javascript-tutorial/server

- add a chapter in the docs about the enhancement of mdtools and move the enhancement proposal for 2.0 as well as large parts of this document there, and only keep this taskpaper for current projects and small things and bug tracking

Cooler website (maybe later):

- move menu icon to the right of next to site icons for moother mobile navigation @later

- smaller headline and less spacing in header for better mobile view @later @done

- search for patterns

- theme picker (text size, white, sepia, dark theme) via session storage: https://javascript.info/localstorage

- responsible map overlay.

- keep menu open

- look at https://javascript.info/websocket: has nice info boxes and a great searchable tutorial map

Links (botstrap etc.):

matrial design for botstrap: https://mdbootstrap.com/ (probably not necessary)

Menus in bootstratp 4:

best practices: https://webdesign.tutsplus.com/articles/best-practices-for-responsive-dropdown-menus--cms-35212

good explanation how to include bootstrap and inclue a menu (which is not layered, so other code would be required for that): https://medium.com/better-programming/an-introduction-to-using-jekyll-with-bootstrap-4-6f2433afeda9

explanation of html/css for responsive menus (nav element and media queries): https://inspirationalpixels.com/creating-a-responsive-menu-with-html-css-jquery/

MVP: Responsive Pattern Map:

Macro Support: @estimate(30min)

- variables:

green: #FF0000

{{name:$green}} or {{name:var(green)}}

- test that variable-name can be correctly substituted in macros and templates (the cfg-object's key is "variable_name")

Plugin and Macro Support: @estimate(8h)

As developer I want a simple plugin API that allows for defining new macros, and access to the preprocessor for preparing required data structures so that I can easily add new behaviour with just a few lines of code

- configure plugins globally and per document type

- plugins used for a specific document can be configured globally or in the preset

- override and extend plugin list in document type

- define parameters per plugin

- add preprocessor plugins

- refactor S3-specific macros to use plugin architecture

Plugin for Clickable Pattern Map: @estimate(4h)

As reader of the practical guide, I want a responsive patter map so that I can navigate effortlessly between patterns.

- add plugin to create html for pattern map structure

- add remplate and JS for pattern map

- add css for pattern map

- add texts to localization.pot if required

Release the practical guide: @estimate(2h)

sync glossary with crowdin:

https://realpython.com/api-integration-in-python/

look at realpython 1/2 pdf

use rest3client to abstract crowdin API https://pypi.org/project/rest3client/#description

- get api token from crowdin.yaml

- ensure glossary in crowdin is set up do distinguish between the followingentry types:

- patterns

- previous pattern names

- pattern category

- "synced" glossary entries

- other stuff (probably best that this category has no markers)

- sync patterns

- ensure all current patterns are present, add those that are missing

- ensure all everything else marked as pattern is now marked as obsolete

- sync pattern category names

- sync glossary entries

- ensure everythinh in glossary.yaml is present, update to the latest description (mark those that are no longer in glossary.yaml as obsolete)

- test by copying the current glossary to a new project

- after running once, clean glossary

Update Language versions to mdtools 2.x:

- update German version

- update Hebrew version??

- update Dutch version

- update swedish version @done

Update documentation:

- move all info from ./slides/slides.md to the documentation tree

- list all macros

- list markup (including escapung/unescaping \{\{ \}\}

- list all filters for the renderer

- list all glossary renderers (for items and for the full glossary is described)

- list relevant config variables are described

- remove obsolete documents

- add a page for each renderer

- set up a separate example project for deckset renderer

Index document can be empty:

As an author I want to have a directory without an index document, so that I have more flexibility for arranging content into different editions.

- what about headline levels? Trade-off might be that those would need to be manually aligned?

Support all editions from one structure:

Build supporter editon and "normal" editions from the same structure, use a config variable cfg.edition (default: '')

If information about inclusion and exclusion is stored in structure (and not in the content file itself) the info is visible in one place. Keeping this info in a separate array, not in tags, allows for a simpler design

Variant A:

add tags to each section: exclude:editon-A|edition-B include:editon-A|edition-B

add as literal to section

id: foobart

exclude:editon-A|edition-B

include:editon-A|edition-B

sections: …

Port revealjs renderer to mdtools 2.0:

At the moment, there are 2 distinct functions, both should be preserved.

render source as deckset

convert markdown to deckset

- remove init in slides, obsolete commands, index and build_web_content

- add new command stub for converting (also to setup.py)

- move files to new location

- find out how both functions interact with each other and update todo list

- test realjs converter with output of deckset renderer

- then convert revealjs renderer

Fix testsuite:

- ensure that all existing tests are running

- check that all main features are not only explained but also used in the documentation so that the documentation serves as a test suite

Redirections: @estimate(6h)

As an author, I redirections on my website so that I can re-arrange my content and change titles as I see fit.

can simply be released when ready

Also I might want to move my site to a new github page and set up a 404 page that redirects all requests?

https://stackoverflow.com/questions/503093/how-do-i-redirect-to-another-webpage

- create first version of redirections.yaml file from structure.yaml

- add template for redirection files (including requred JS)

- add configurable build step for generating redirection files from redirections.yaml

- add search

Link to Node:

As a reader I want links to content nodes in the PDF, the EPUB and the all-in-one webpage, so that I can click on references in the text, and especially in the list of patterns.

Sometimes:

- full support for YAML metadata in Markdown source files

MVP: App with GUI:

As author I want a simple app that converts my stuff to so that I don't have to mess with installation and teh commandline.

(people would still require to install MacTex, Jekyll, Pandoc etc., though)

- build a gui (from on I already have probably)

- select project file

- select a preset

-- run | quit

- log level

- log output

- test if pandoc, latexmk or multimarkdown is installed (is mmd necessary at all??)

-

- execute the build

MVP: Better Document Structure:

Better Document Structure: @estimate(6h)

As an author, I want to use identical file names in different folders so that I don't have to use weird workarounds, e.g. when each part starts with an 'overview' .

- error is raised if both exist at the same time

- website is published in folders now

- all indexes and menus are still working

- update redirections as necessary

Release: @estimate(2h)

this release might require moving some files in Crowdin!!! @priority

- backup all files in crowdin!

- manually move files in crowdin!!!

- release

Add separate template command: @estimate(2h)

cmd_template is working with new config format

requires some thought, because of new config format, running it with full config is a lot of hassle,

manually handing in translations and variables is also not right for some usecases.

Therefore it makes sense to wait if this is needed at all, and if so, in what way

Better glossary and links support for Latex (and other formats): @estimate(4h)

Make handling glossary and section links more flexible to enable output in PDF

most of the code is already there, requires some tweaking though.

- add markdown rendering for emphasis and strong in glossary text

- render glossary terms as footnotes for LaTeX

- render section links as clickable links in LaTeX (like in the index)

- render section links as clickable links in ePub

Basic Footnoote Renderer for Ebooks:

replace glossary link with a footnote marker for that glossary term

Glossary for Epub:

glossary can be footnotes, or an epub glossary, but epub glossaries don't seem to be universally supported:

http://www.idpf.org/epub/dict/#sec-1

https://ebooks.stackexchange.com/questions/2344/epub-kindle-file-glossary-and-dictionary-selection

https://support.apple.com/kb/PH2753?locale=en_US&viewlocale=en_US

https://pressbooks.com/blog/our-gifts-to-you-this-holiday-a-new-glossary-feature-customizable-section-labels-and-more/

https://www.wikihow.com/Write-a-Glossary

Glossary for PDF:

Try footnotes, one footnote per glossary entry, or underlining all glossary entries with LaTeX markup (or both)

dotted underline https://tex.stackexchange.com/questions/27258/how-do-i-write-underline-text-but-with-a-dotted-line

underlines with ulem: http://texdoc.net/texmf-dist/doc/generic/ulem/ulem.pdf

undeline in Latex: https://alexwlchan.net/2017/10/latex-underlines/

- try https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide#glossaries

Support for Open Graph tags:

simple stuff that goes in the page header, can be configured via _config.yml

https://en.wikipedia.org/wiki/Facebook_Platform#Open_Graph_protocol

used by facebook, twitter, google, and linkedin: https://stackoverflow.com/questions/10397510/do-services-other-than-facebook-use-open-graph

Done: @done

Convert Layout to bootstrap: @done

use bootstrap 4 first because that works with jQuery and smartmenus, then see about bootstrap5 (which *should* also work)

- bug: menu button snaps sooner than menu space

Notes for adaptation in projects:

- index.html: markup and version text: .small

- replace all the css!

- test what happens to plain template (pattern map)

- make sure texts for prev/next are added to translation memory

- make sure page.html is added to contents/website/_layouts and added to projects.yaml

- make sure to upfate menu.html

The Basics: @done

- add bootstrap 4.5.x (css and media query, css below the site) @done

see https://getbootstrap.com/docs/4.0/getting-started/introduction/

- add to templates/default.html @done

- add to plain.html @done

Clean up CSS: @done

- update strutude (base / content / layout) and put everything where it needs to be @done

- check what is still necessary, and what can go @done

- use bootstrap's clearfix where possible @done

- fix typography to use bootstrap @done

- make sure menu uses proper media queries @done

- check _base.scss for othe obsolete things @done

- Replace media queries with bootstrap code @done

Switch to popper.js for tooltips: @done

https://www.geeksforgeeks.org/bootstrap-4-popover/?ref=lbp

- add js from https://popper.js.org/ @done

- replace styles @done

Quick and dirty redesign with bootstrap for a simpler and cleaner look:

Overview

Menu on the left border of screen,

conten centered and a little wider

lightboxes for illustriations on desktop so that they don't mess up the pages

simple nav buttons < > around content or below on mobile

index.html stays as it is

- decide about information to keep in footer, where would that go? @done

- fix icons in menu.html (and add class="icon") @done

New Two Column Layout: @done

- content is centered, but with maximum size (see https://www.geeksforgeeks.org/bootstrap-4-holy-grail-layout/?ref=lbp) @done

- Header: convert to grid @done

Footer: @done

- use grid @done

- make it look good @done

- remove superfluous styles @done

Menu: @done

menu on the left side of screen, with a slightly grey background, and a scrollbar

search-bar for patterns will come on top above the menu

menu div gets a scrollbar

add note: "published with mdtools"

Smartmenu bootstrap pugin only works for HORIZONTAL navbar menus!

smartmenu appears to be working fine as it is

- style menu @done

- bug: footer must start below menu at all times!! @done

- fix menu and content resizing @done

Fix typography: @done

- Set base font size @done

- use .small for footer etc @done

- remove all superfluous styles @done

Illustrations: @done

- Step 1: make them responsive (simple) @done

https://www.geeksforgeeks.org/bootstrap-4-images/?ref=lbp

- Step 2: make them nice (takes a bit more effort) @done

add lightboxes make sure illustrations don't look like shit because long things are stretched ultrawide

e.g. https://mdbootstrap.com/docs/b4/jquery/javascript/lightbox/ deactivates on mobile automatically, that's nice

Cleaner navigation: @done

keyboard navigation is now broken, because I moved all javascript down the page

quick and dirty solution: render links with id = "nav-next" and "nav-prev" and grab their url via javascript - BUT prev/next is not part of the content but page metadate and should be added to yaml front matter (will appear as global variables in liquid)

- make mdbuild add prev/next_page_url and prev/next_page_title to front matter of content @done

- add < and > as navigation buttons for next/prev (using new icons) @done

- find a way to add first page to navigation so that 'g n' from the homepage leads somewhere @done

- setup color and mouseover @done

- add to bottom of page so that it looks nice enough @done

- map left and right arrow keys to browse quickly through the pages @done

- add <link rel="prev"|"next">? to html header? @done

- bug: the content area is moved to the left slightly @done

Styling the summary: @done

The summary should not require formatting in the actual summary to make it stand out.

- replace strip_summary_tags with summary_format=jekyll/epub/latex/plain (metadata.py!!) @done

- wrap summary in <p class="well(-sm)> and add styles for page and epub, remove ** @done

- wrap summary in ** for LaTeX output if it isn't already (because that won't break anything), but a nice box would actualle be the thing to do @done

- fix tests!!! @done

MVP 1: New Structure, Menu and CSF: @done

After the first milestone, the Common Sense Framework can be integrated into the practical guide.

This release affects crowdin! @priority

New Project Structure: @estimate(2d) @done

As author, I want a more flexible and consistent document structure so that I am not limited to a fixed three-part structure (Introduction, Chapters, Appendix)

Constraint: each section still requires a unique id (filename name) as we don't have folders in the first release @priority

Can't be released without a new menu for the website, because new content will not be visible @priority

Responsive Website Menu: @done

As a website visitor I want a responsive menu that gives me access to all content, so that I can find what I want.

Release of the Practical Guide: @done

This release removes dependency of translation to structure.yaml.

As soon as all new templates are translated, other language versions can be updated, too, the CSF will then be added as an update as soon as it has been translated.

Linkable Glossary: @done

Glossary items should instead be rendered as dd tags within a dl (definition list) and they should have anchor links so that one can link such as https://patterns.sociocracy30.org/glossary.html#objection which isn't possible now.

Show/hide parts of content files dependent on format, preset and edition: @done

As an author I want to be able to show parts of a file only for specific formats, editions or presets, so my project is easier to maintain.

Simplified Structure (won't do): @done

Check that a simplified format for structure (like used in the docs) is still possible

It doesn't appear to be possible. Converting a project to the new structure is simple and well worth the effort.

Better User Experience for Website: @done

- add smartmenu keyboard navigation addon @done

- add keyboard navigation for next page @done

Update documentation: @done

Showcase features and document usage of mdtools in a documentation that is created with mdtools

…

- copy all necessary stuff (including the makefile) from S3 repo @done

- setup project yaml from S3 practical guide @done

- convert filesystem structure @done

- copy all files from docs folder @done

- conver structure.yaml @done

- integrate makefile @done

- convert all templates @done

- convert .tex @done

- convert project.yaml @done

- convert _config.yml @done

- convert epub header @done

- ensure everything inside content/website is updated @done

- @done

- attempt quickfix of deckset renderer jsut for fun @done

- move documentation from /doc-src/en to .content @done

Port Deckset renderer to mdtools 2.0: @done

processing slides:

set up basic test for all important formats (gold master): @1h

make sure all relevant features are covered

- speaker notes

- glossary renderer and page breaks (at least 3 glossary entries)

- inline images

- section numbering

- image captions

reveal.js renderer: @later

- section links [Governance Facilitator](section:governance-facilitator) : replace with emphasis on title

- glossary overlays [Driver](glossary:driver): add html overlay

- add support for right aligned images

- have chapter links link to slide https://github.com/hakimel/reveal.js/#internal-links

- revealjs: add html overlay for glossary terms

Style/Theming:

see https://github.com/hakimel/reveal.js/blob/master/css/theme/README.md

- paragraphs are centered, should be aligned right (.reveal .slides { text-align: center;}

- some slides are truncated (affects text-only slides also). Those slides are displayed completely when reducing the screen width

mdimg:

- (optional) parse non-language assets?

- as of now, using one language only no longer works, this needs to be remedied @priority(high)

Multi-language Support:

- document structure in readme or help

Image repositories structure:

Assumption: documents may reference images from all languages

there needs to be a common root for for images "img", which is symlinked into each folder that makes use of the images. Otherwise folders become messy quite soon.

- Maybe that root folder can be called something else to cater for something else? If the code is clever, the root folder's name is not important, and image references will be translated accordingly. Then we could also use mdimg to rename the root folder form "img" to, say, "assets"

/img/

/de/...

/en/…

/slides/

/de/…

/en/…