[ANN] PkgPage.jl build a nice webpage for your package in minutes

Hello!

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.

@zlatan 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.

To get started: add the package and follow the instructions.

We hope you’ll find this useful!

ps: thanks to @Wikunia for beta testing and help with the code!

PPs: here’s a screencast of me using PkgPage live (be nice, I’m not very good with this screencasting thing)

69 Likes

Looks great! If only I had a package worthy of this treatment…

1 Like

It looks great (I am a happy user of Franklin in a very small website).

It is a nice option to create a website without worrying with the HTML, or the template, good work!

1 Like

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.

3 Likes

If you make a page for your package with PkgPage, it will start to seem more worthy… :wink:

2 Likes

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.

1 Like

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?

1 Like

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).

3 Likes

Hmm that’s true :thinking: I wonder if this can just be specified with .gitattributes and via GitHub linguist, does anyone know?

It looks like setting a .gitattributes specifying the path of the page as vendored should work; I’ll play with this tomorrow and see what we can get

Ps: CDN is not ideal bc it won’t be purged

Looks really nice!

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).

1 Like

Bootstrap 5 is dropping jQuery. It should be out soon.

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).

I’ll add this in the instructions.

3 Likes

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… :frowning: ); 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…

3 Likes

Good find, thank you! :slightly_smiling_face:

This is fantastic. Has anyone tried it already? I you have, could you post a link?

1 Like

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).

4 Likes

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.

3 Likes

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?

2 Likes

I personally would like something more prominent, like a “View on GitHub” button.

It might not be obvious to people that the “Star” button is the fastest way to get to the GitHub repo.

7 Likes