😎 Port site to mystmd (work in progress)

[brianhawthorne]

Implement site as a mystmd book instead of as a Hugo site.

Closes #77

[stefanv]

Neat, thanks Brian!

I notice:

• The footer columns are a bit narrow.
• Under "Organization" the cards could be a bit wider, like on the front page.
• Under GitHub, there are so many cards that we probably want to drop these into a table?
• Under about, could we reduce the spacing above/below images a bit? Not important.

Nice work, thanks!

[bsipocz]

Thank you for working on this. I have some preliminary comments, none of which is content related and don't have the preview link.

So I would think we should commit the CI config to main independently, so the preview is being picked up for the PR.

[bsipocz]

I would just leave this file alone an append any new ignores to it.

[bsipocz]

@jarrodmillman and @stefanv can comment if we also use this refactor for restructuring/restarting the team? This list was made at the second summit and since then people seem to have less time for this team while others stepped up.

[bsipocz]

This is all good now as the toc is not too long, but overall I would advocate for keeping the toc and the myst config separate.

[brianhawthorne]

Are you thinking add a separate _toc.yml like described here: https://mystmd.org/guide/table-of-contents#toc-format-legacy (as deprecated)?

Or is there a newer way to include a separate chunk of yaml as sub-config into the primary myst.yml?

[stefanv]

Or is there a newer way to include a separate chunk of yaml as sub-config into the primary myst.yml?

Huh, pretty sure this is possible now, but I can't find the PR or the docs entry!

[stefanv]

Aha: https://github.com/jupyter-book/mystmd/pull/2362/files

[stefanv]

(Give a thumbs up on that PR, if you get a chance, please!)

[bsipocz]

Docs already exist here: https://jupyterbook.org/stable/authoring/table-of-contents/#external-toc-files-using-extends

(and out in the wild, I use it here: https://github.com/Caltech-IPAC/irsa-tutorials/blob/main/myst.yml#L22)

[brianhawthorne]

Great - thanks Brigitta and Stéfan!

I had only looked at the TOC page in the myst guide and there's no mention of it there. The jupyter-book guide wasn't even on my radar, but now I'll know to search there too! I also found a handful of other spots in the myst guide that mention extends but which are not found in the jupyter-book guide:

• https://mystmd.org/guide/document-parts#share-the-same-part-across-multiple-sites
• https://mystmd.org/guide/frontmatter#composing-myst-yml
• https://mystmd.org/guide/authorship#re-use-author-information-across-repositories-and-projects

What is the relationship between the two guides?

Feels like we're missing a documentation page describing the myst.yml file itself. Maybe "Configuration" under the "Reference" section? That could

• Detail exactly what keys are expected/accepted there, which ones are optional vs required, summarize what they mean, then link out to those more specialized pages dedicated to authors, toc, frontmatter, parts, ...etc.
• Explain the difference between project and site.
• 👉 Describe the extension mechanism.
• Mention the --config CLI option.
• ...

Thoughts?

[brianhawthorne]

If no one else has brought this up / made a ticket, I could mention in the #documentation thread on Discord; but I'm probably not the best person to execute on it..

[bsipocz]

I had only looked at the TOC page in the myst guide and there's no mention of it there. The jupyter-book guide wasn't even on my radar, but now I'll know to search there too! I also found a handful of other spots in the myst guide that mention extends but which are not found in the jupyter-book guide:

This is all quickly evolving, it got the extends suggestion on discord. Then I remembered to point out to the review of the jupyerbook docs, but apparently it hasn't yet made its way to the myst docs.

There are a bunch of open docs PRs for mystmd (one about extends others about better structuring to help discoverability of config options, etc), hopefully they will get merged and then we can do a better sweep for still missing things.

I fully agree that the guides and docs are not consistent, and I personally find it still very difficult to find things in the mystmd docs where I assume they should be.

So, overall, I think you should open issues for any of the inconsistencies you run into, at least to put it on the radar of people.

Anyway, back to this review comment, this is one of those that doesn't need to be addressed in this PR. Get this all run is more important, we can then tweak the content in a follow-up, if necessary.