The bookish from amyjko

Syntax highlight code

Use highlight.js to syntax highlight preformatted text.

https://www.npmjs.com/package/highlight.js

Quotes

Need a syntax for quotes. Perhaps mirror the code block:

"
This is my quote
" credit

This is needed in the first chapter of the Design Methods book.

Prettier loading messages

Currently just using text. Add some loading images instead.

Show progress on chapter

This is actually two features:

Place a progress bar somewhere to motivate finishing. This can just be a simple visualization anchored to the footer. It can be based on the percent stored in local storage.
Place a percent read in the table of contents.

Improved error handling for book specifications

Check all possible errors and include appropriate warnings. We currently fail to check for any and provide no errors to the user.

JSON syntax errors
Peruse syntax errors in various fields
Missing content in the book specification.
Missing images, captions, alt, credit for chapters and covers.

Perhaps embed AJV and verify against a schema with custom error messages.

Executable code

Python3 in particular would be most helpful, since that's mostly what I'm using in the book.

Use superscript numbers for citations

The dot grabs a little too much attention. The tricky thing about this is actually counting. We have to get through the document to find all the citations, figure out what order they're going to appear so we can number them, then use those numbers in rendering. We probably need a first pass.

Citation links should provide feedback when navigated to

They currently just scroll down, but there needs to be some kind of highlight.

Reading: Allow commenting

On the sentence level. Click or tap on a sentence and highlight to comment. These will be stored in localStorage, with a warning that they'll only be saved on the device. The table of contents would show comments for easy navigation. Need to ensure that all text is wrapped in a span so that it's highlightable.

Content: Tables

I despise the complexity of the Markdown syntax. Let's do something simpler.

Change file extension to something other than .md

While there are some similarities to Markdown, there is a custom syntax here, and we should signal that. Perhaps just .txt to signal that it should be opened by a plain text editor.

Handle HTML entities correctly

For example, — doesn't render correctly. See Chapter 2 of Design Methods.

Search the whole book

It should be possible to search the book on the front page. There can be a simple text box, minimalist styling, which will replace the chapters with linked search results to the occurrences. To do this, we'll need an index of the chapter content that's computed after all the chapters are done loading.

Reading: Bookmark sentences

In addition to comments, allow bookmarks, and create a page in table of contents that shows bookmarks for easy navigation.

Citation numbers are wrong

Numbers are duplicated and don't correspond to the list in the references.

Reading: Linkable paragraphs and headers

This we, we can easily share or quote specific sections. This shouldn't be too difficulty with the routing functionality in place. I just need to actually scroll to the appropriate paragraph or section.

Allow swipe navigation between chapters

Quick return to other chapters on mobile devices. The order would basically be table of contents, chapters, then index.

Add an .htaccess to the example for proper routing

This won't work for every web server, but there are options for many platforms. https://link.medium.com/Ng3zMVCYn9

Reduce bundle size

It's currently about 1 MB, which seems outrageously large for such a tiny React app. There are tons of tips out there for how to reduce its size.

Reading: Dark mode

This will allow for better reading at night.

Starting a paragraph with a * shouldn't bulletize it

For example

Speak loudly and carry a big stick should just be a paragraph, not a bulleted list. The space after the star matters.

Track read status locally

This will allow one to keep track of where one is in the book. Probably do this per chapter, with a percentage, and upon app load, scroll to that percent instead of the top, or the top if undefined. Then, on scroll, update local storage.

Navigation bar on chapter pages

Table of contents, previous chapter, headers in chapter, next chapter, index. Not sure what this should look like or where it should be on mobile, if at all.

Content: Make first word in chapter fancy format

Larger, floating, taking up two lines.

Content: Support non-numbered chapters

Preface, introduction, appendices, etc.

No need for book specification name

Just require the JSON file to be named book.json

Add citation format

Perhaps a way of referring to something in a central citation list embedded in a specification.

Search chapter content

It should be possible to easily find keywords on the page. Highlight them. Just start typing to search. We'll need a per chapter index to compute this, but we can reuse the book-wide search to implement and highlight this.

Less distracting citation symbol

The bullet is a little bold; perhaps a Unicode document symbol instead, or a small dot.

Horizontal rules

This will be handy for lightweight segmentation of content.

References page needs a navigation link too

Probably just back to the table of contents.

Scroll on route link

When clicking on a Link that follows a route, the page needs to scroll to an appropriate place.

Content: Footnotes

Cite them in the text, put them before references. I was thinking of a syntax like this:

This is my sentence {and this is my footnote}

Where all content in curly braces gets automatically pulled out, numbered, and linked.

Convention for footnotes is superscript numbers, so we might need to change the reference format, which currently uses superscript numbers.

Automatically replace plain quotes with smart quotes

Add support for links to routes

See, for example, the link in rules in the Informatics teaching guide, to the prepare.

Allow markdown in book specification content

This will require extracting the parser from chapter and making it a reusable component.

Content: Callouts

These would be content that that have formatting around them, to distinguish them from the body text, like a code block, but not pre-formatted.

Reading: Chapter outline navigation links

Show chapter title, all headers, table of contents, next and previous chapters. This could also be next and previous header links.

Property track navigation via Google Analytics

So I can track book reading.

Single-page mode

For those that want to convert the whole book to a PDF or read it cover to cover.

Reading time estimates

Add them in the table of contents.

Reading: Controls to influence font size

Not all browsers do this well. Add some app controls that allow easy adjustment. Perhaps a fixed position settings control floating in the corner that, when clicked, shows font size controls. I could put this in the margin of the navigation bar and toggle between different sizes.

Allow authors to be markdown, so we can link to author web pages

If we just have the author field be markup, then we won't have the author name for other purposes as a plan string without parsing it. Maybe ask for author link separately.

Convert to hash router to remover server dependency

This will simplify installation and make the paths a bit uglier.

Add navigation links at the top and bottom

To TOC, previous chapter, next chapter

Add chapter number, book title, authors to chapter header?

Pros: single pages can feel disjoint from header and be linked to.

Cons: clutter.

Generate index section

Shows all keywords and phrases with links to occurrences, and occurrences are highlighted on the page.

From a chapter parse, need to index all words by the chapter in which they occur
Across all chapters, need to aggregate all words and the chapters in which they occur
In the chapters, need to highlight the words everywhere they occur within the chapter. Split text nodes into word spans with a class corresponding to the word they are for easy CSS highlighting.

Content: Mathematical formulas

MathML isn't fully supported (on Chrome or Edge), but there is partial support on WebKit and Firefox. There are some polyfills:

https://www.w3.org/wiki/Math_Tools

We'd need to add a syntax for including these, but it could be as simple as just segmenting it as a block escape format with embedded a MathML syntax.

https://www.w3.org/wiki/Math_Tools

Another option seems to be MathJAX, which seems pretty well supported:

https://www.mathjax.org