Skip to content

Migrate to mdBook#292

Merged
avivace merged 2 commits into
masterfrom
mdbook
May 24, 2021
Merged

Migrate to mdBook#292
avivace merged 2 commits into
masterfrom
mdbook

Conversation

@avivace
Copy link
Copy Markdown
Member

@avivace avivace commented May 18, 2021

Why:

  • single and multi page layout
  • themes, palettes, better theming
  • custom backends
  • custom language highlight.js

What's missing:

  • info/warning boxes renderer
  • Styling those boxes
  • Re-wiring CI
  • Fixing links
  • Custom highlight.js
  • Making heading levels consistent
  • Make info/warning boxes render on print

Fixes #289
Fixes #290
Fixes #7, since we're not using Vuepress anymore
Fixes #19 by virtue of using custom themes, though a custom "Pan Docs"/"Classic" theme could be added.
Fixes #58 due to an entirely different layout
Fixes #60

Comment thread docs/.nojekyll Outdated
@@ -0,0 +1 @@
This file makes sure that Github Pages doesn't process mdBook's output.
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is not needed, it's sufficient to not enable github pages with jekyll in the repository setting and github pages will just serve the selected folder / branch

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's automatically generated, and I'm not seeing a way to disable it.

Comment thread docs/About Outdated
@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 19, 2021

@avivace How are we going to handle the custom styling of the boxes? Also, should we offer the current Pan Docs color scheme as a theme? (If yes, there are a lot of corollary questions.)

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 19, 2021

Misc. changes to be made:

  • LCDC.md, line 57 says "further below", but this is not below anymore.
  • Video_Display.md is huge, and generates a beeg chapter without a ToC, so it should be split into multiple sub-chapters. (We can use the navbar's collapsing feature to avoid making it huge as well.) Changed, though STAT still has the interrupts, which imo should be moved elsewhere. Done.
  • SGB_Functions.md is huge as well.
  • CPU_Comparison_with_Z80.md compares with Z80 and 8080, so a slightly more generic name would be more appropriate.
  • "MID-FRAME QUIRKS" box isn't marked up in the Video Display chapter. Fixed, all boxes mark up correctly now, with a slight added restriction, which is documented in the README.

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 19, 2021

How should glossary entries be marked up?

@ISSOtm ISSOtm force-pushed the mdbook branch 2 times, most recently from 7c4ae40 to dea7045 Compare May 20, 2021 21:19
@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

A preview is now live! Feedback is welcome.

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

Note: to test CI, as well as to update the preview, I am now pushing to https://github.com/ISSOtm/pandocs/tree/master instead.

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

I also consolidated the build and deploy CI workflows into a single one, so that the build's results can be immediately used. Deployment is skipped when not pushing, pushing to a branch that isn't master, or if a SSH deploy key hasn't been configured.

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

Since this has a custom PDF export (via the browser), can we consider #57 fixed by this?

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

Everything is done besides the glossary markup, but that still has to be added separately, so there's no point in blocking the rest of the improvements. I'm waiting on @mid-kid's discussion on #18, and any other feedback that may surface.

If no opposition is brought up, then I will push the changes to this branch and merge them.

@avivace
Copy link
Copy Markdown
Member Author

avivace commented May 21, 2021

Great work @ISSOtm . This is gorgeous.

The Glossary markup is not a priority for the migration PR. It wasn't there before, it's not necessary to have it now before migrating, it could be secondary task after we migrate to the new rust-based pipeline.

@avivace
Copy link
Copy Markdown
Member Author

avivace commented May 21, 2021

Since this has a custom PDF export (via the browser), can we consider #57 fixed by this?

Nope, I think we already brought that up but we could've done that before too and the PDF exported by a print from the browser does not provide a decent table of contents, etc so that issue still stands.

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

Since this has a custom PDF export (via the browser), can we consider #57 fixed by this?

Nope, I think we already brought that up but we could've done that before too and the PDF exported by a print from the browser does not provide a decent table of contents, etc so that issue still stands.

Well, it's a hack, but since we have control over the renderer, so I can either edit print.html in-place, or generate an alternative version with a ToC.
Alternatively, I'll see if there is a PDF renderer for mdBook, or one to a format that can be easily converted to PDF. I've seen ePub, for example, but I don't know.

By the way, since we have a ToC for navigating to a page, and the pages themselves are small enough (except "SGB Functions", which probably needs to be split), should we consider #60 fixed?

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

mdbook-latex is worth looking into; if we can't get it to work, its README links to other projects that look potentially useful.

@avivace
Copy link
Copy Markdown
Member Author

avivace commented May 21, 2021

Since this has a custom PDF export (via the browser), can we consider #57 fixed by this?

Nope, I think we already brought that up but we could've done that before too and the PDF exported by a print from the browser does not provide a decent table of contents, etc so that issue still stands.

Well, it's a hack, but since we have control over the renderer, so I can either edit print.html in-place, or generate an alternative version with a ToC.
Alternatively, I'll see if there is a PDF renderer for mdBook, or one to a format that can be easily converted to PDF. I've seen ePub, for example, but I don't know.

By the way, since we have a ToC for navigating to a page, and the pages themselves are small enough (except "SGB Functions", which probably needs to be split), should we consider #60 fixed?

I agree on closing #60. For the PDF export, I still want to consider merging everything into a single MD/latex file and the render an actual PDF (and HTML, for the single page export) from there.

@ISSOtm
Copy link
Copy Markdown
Member

ISSOtm commented May 21, 2021

For that, I think the renderer I just linked could do a good job. We should look into it after merging this PR to avoid scope creep, though.

@avivace avivace marked this pull request as ready for review May 21, 2021 22:08
@avivace avivace changed the base branch from develop to master May 24, 2021 08:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Easier navigation of Pan Docs ToC depth Empty sidebar? Gray background headers Usage of Vuepress' Custom Containers

2 participants