Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prototype landing page edits #557

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

choldgraf
Copy link
Member

@choldgraf choldgraf commented May 1, 2022

This is a prototype to play around with better "landing page" style structure, using page-level metadata. Would love feedback about whether this design seems nice and if it is an improvement. Here are the major changes:

  • Adds page-level metadata. This has a structure like the following (meant to be put in the markdown file's YAML metadata):

    theme:
      collapse_sidebar: true
      full_width: true

    If that is in the page metadata it will either collapse the sidebar by default, or make the page full-width by default.
    In addition, there are now global configs for this as well.

  • Updates the padding on full-width + collapsed_sidebar. If the article is set as full-width, and the sidebar is collapsed, then we add extra padding and center the content, so that it looks more like a typical "landing page". This should hopefully make it more suitable

Here's how it looks on our docs. The following is the default behavior when people land on the page. If they go to sub-pages, the sidebar will start showing up again.

image

ref: #162 (I think this is a step in that direction but may not totally address it)

@@ -1,5 +1,8 @@
---
title: The Sphinx Book Theme
theme:
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
theme:
theme_html:

(or html_theme)

this makes the purpose clearer, and would allow for e.g. the future addition of theme_latex etc

Copy link
Member Author

Choose a reason for hiding this comment

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

what do you think about nested?

theme:
    html:

Copy link
Member Author

Choose a reason for hiding this comment

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

ah I just realized that this might be weird to parse in Sphinx though, since the nested levels are stringified right?

Copy link
Member

Choose a reason for hiding this comment

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

I guess partly it depends if/how you want to have this work with RST.
For that you can only do non-nested field lists, e.g.

:name: value

so even html_theme + variable keys, won't "work", e.g. you would need to do:

:html_theme: {"key": "variable"}

For myst, yeh everything under the top-level key will be serialized to JSON, but then you would just need to deserialize, when you read it from the env.metadata[docname]["html_theme"]or env.metadata[docname]["theme"]

Copy link
Member Author

Choose a reason for hiding this comment

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

My feeling is that we don't want to constrain MyST (or Jupyter Book) on what is possible with rST. I'd be OK with telling users "if you want nested metadata in the header, then your content should be MyST". Any objection to that?

I have a slight preference for:

theme:
    html:
        foo: bar
    latex:
		foo: bar

over

theme_html:
	foo: bar
theme_latex:
	foo: bar

but not a strong opinion, what do you think?

Copy link
Member

Choose a reason for hiding this comment

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

yeh, no strong preference either

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.

2 participants