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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Custom Title/Landing Page #162

Open
chrisjsewell opened this issue Aug 7, 2020 · 3 comments
Open

Custom Title/Landing Page #162

chrisjsewell opened this issue Aug 7, 2020 · 3 comments
Labels
enhancement New feature or request
Milestone

Comments

@chrisjsewell
Copy link
Member

chrisjsewell commented Aug 7, 2020

Most books that I've seen have a front cover 馃槈

I think it would be great to have an (optional) front page which has a very distinctly different layout to the rest of the pages.
It might even be better if (somehow) this page is not even parsed from a standard rST/Markdown page (like the current index.html),
but is related to a bunch of variables, and a separate HTML template (similar to LaTeX title pages).
e.g. something like you specify the variables:

title: This is my title
author: My Name
abstract: |
    This is my abstract

which get parsed into a standard or custom frontpage template:

<h1>{{ title }}</h1>
<p>by {{ author }}</p>
</br>
<p>{{ abstract }}</p>

(but obviously more fancy like https://dev.to/davidepacilio/40-free-html-landing-page-templates-3gfp)

I don't know if this needs to be something implemented upstream (like pydata/pydata-sphinx-theme#146) or we can do here.

@chrisjsewell chrisjsewell added the enhancement New feature or request label Aug 7, 2020
@choldgraf
Copy link
Member

I agree something like this would be quite useful. I guess my question is whether we should special-case this at the level of HTML / templating / etc, or if we should ensure that we provide the right Markdown syntax elements + documentation to customize them so that people can accomplish this on their own.

I suspect that the latter would be easier to maintain if we were able to get where we wanted. And Sphinx already treats the master_doc page as "special" and not integrated w/ the rest of the book structure.

For certain page elements, like the title / author / etc, I think we could definitely special-case some page / site variables etc. We may want to explore that "title/author" pattern for other pages too.

btw, I like that our feature voting thing is now encouraging people to +1 their own issues 馃槄

@choldgraf
Copy link
Member

I looked into this a little bit more and it sounds like it should be pretty doable with a custom template + this config in Sphinx:

html_additional_pages = {
    'index': 'landingpage.html',
}

That'll render the Jinja template landingpage.html to index.html in the built site, and we have access to all the site variables etc.

I think we'd need to over-ride Jupyter Book's current behavior regarding the index.html in this case (which is to add a re-direct to the first page of the book). But other than that I bet it'd be straightforward for us to bundle a nice landing page template w/ Jupyter Book and then offer a flag to turn it on.

@mmcky
Copy link
Member

mmcky commented Apr 11, 2022

We were just discussing this idea at quantecon and having a custom landing page would be a really useful feature such as a sphinx-frontpage extension. My search on the web landed me here :-).

cc: @AakashGfude any thoughts on how hard this would be as a simple sphinx extension?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants