A while back @viralbshah asked me whether it was possible to have a way to create a single-page webpage for packages “really easily” with Franklin, well, here it is.
@anon37204545 and I are happy to announce PkgPage.jl a package that builds on Franklin.jl with a single-page bootstrap 4 template that is mostly pre-arranged so that you won’t need to fiddle with HTML/CSS to get a nice looking landing page. The layout and colour scheme can easily be customised (e.g. use a hero, a different logo, add a link to docs, wider or narrower body etc.)
Here are a few reasons why you might want to consider this:
it will look nicer than a GitHub README
you can show maths (with KaTeX)
you can use any highlightjs theme
you can demo Julia code that gets evaluated on the fly
easy to use, no need to tweak HTML or CSS code to get a good result (you can if you want a more custom look)
Note also that even though it uses the Bootstrap framework we:
don’t use the Javascript that comes with it (jQuery), we only use a tiny vanilla JS script for the scrollspy (which you can disable); KaTeX maths and highlightjs code are pre-rendered by default,
use purgecss in the deploy phase to decrease the size of the boostrap stylesheet from 160K to ±10K.
So overall the generated page is responsive and light.
Great work! Putting a high-level summary at the gh-pages root with PkgPage and API reference on dev/stable/etc. with Documenter seems like an awesome combo.
Quick question: Is it required that the Bootstrap CSS be committed to the repo? That would have the unfortunate side effect of turning any repo that uses this into a CSS repo according to GitHub.
Not necessarily. There will likely be more HTML than CSS (because the CSS is minified), so it would be HTML. But if there are Julia examples on the page, then it might have more Julia. I have a couple of Franklin repos, they display as HTML or Julia.
Ideally I’d like to keep both HTML and CSS that I didn’t write myself out of my repo. Perhaps a build process similar to that of Documenter could be used?
In that case, you just need to replace the CSS that is in there will the CDN-served versions. You could maybe do the same with any custom CSS they have for this package (haven’t looked at the source).
Probably not worth the change, but if you are interested in a “javascript free” css framework, I’ve been quite happy with Bulma in the past (other than for the lack of javascript, it is at least superficially similar to Bootstrap, maybe a bit more lightweight).
Just in case people are wondering about this; @christopher-dG made a great point that things as they stand would make your repo look like it’s basically a web repo with lots of CSS and HTML instead of a Julia repo. It’s actually super simple to avoid this by adding a .gitattributes file where you ignore the page/ path (or wherever the source is):
page/* linguist-vendored
see the file on PkgPage (which is now marked as 100% Julia).
Yeah there’s a lot of great frameworks and themes out there; but even though Franklin makes it fairly easy to work with anything you want; it always requires a bit of time to adjust everything so that it #just-works (and that you’re not left with a bloated JS mess… like, unfortunately, a lot of Jekyll and Hugo themes… ); it’s my hope to keep adding themes and examples using frameworks in FranklinTemplates but it’s a fair bit of work (and I’m far from an expert in web dev…); help is very welcome (and kudos to those who’ve helped me with this effort!)
I’m hopeful that over time we will have more and more of these “here’s a nice template you don’t need to tweak and can directly dump content in” rather than barebone themes that currently still have to be tweaked a fair bit…
Well PkgPage’s page is made with it (but I guess you knew that); actually when you do newpage(); serve() you start with PkgPage’s page; the two source files to modify (config.md and index.md) serve as both a starting point and a tutorial (they contain fairly exhaustive comments).
Just something I noticed looking at the landing page: Maybe it might be useful to have a more prominent link to the corresponding GitHub repo right at the top? I often find myself wanting to look at the actual code, when reading docs.
Star button is actually just a link to GitHub repository. Where would you put it, to make it more prominent? Or you’d rather have it replaced with just some sort of “View on GitHub” button?
I wonder if this can just be specified with .gitattributes and via GitHub linguist, does anyone know?
); it’s my hope to keep adding themes and examples using frameworks in FranklinTemplates but it’s a fair bit of work (and I’m far from an expert in web dev…); help is very welcome (and kudos to those who’ve helped me with this effort!)