Waterfall theme for blogger

[Moelf]

Hi,

really appreciate the work being down here. I once put together a barebone SSG using Mustache.jl and Weave.jl only to realize the work of JuDoc.

The templates we currently have feel more for docs than for blog posts? As there's no continuous way of going through all the posts (?). An example of waterfall design: https://spreadprivacy.com/

[Moelf]

for example, in hyde, I don't find a way to display all posts other than writing a script to generate a index.md for this purpose. Also, entries such as website_title the config.md seems being over written because we're alwasy landing on index?

[tlienart]

Hello Moelf, thanks for your feedback!

JuDocTemplates has not received as much love as JuDoc and help / feedback is very much welcome. One of the reason behind this is that I originally wanted to just have "decent starting points" that people could easily tweak however they wanted (without having to dig through a ton of CSS / JS) and, hopefully, contribute back here with templates that would improve over time. So, yeah, I definitely agree that the templates are far from perfect and that having more would be nice 😅

First question

Are you referring to chronological posting? where you would have a page with an ordered list of all the posts?

If so then currently JuDoc does not natively support this (yet). It can be achieved through a maybe convoluted side way: to write a Julia code block that browses your files and displays them (see below for a rough way of doing this). This may in fact be similar to what you've done except it's executed by JuDoc.

If not then would you mind providing a rough sketch of what you'd want to find?

Second question

See maybe the code below. With respect to website_title, this is a bit different, apologies if it's confusing. That variable relates to the generation of an RSS feed and is required by it, see https://tlienart.github.io/JuDocWeb/pub/syntax/page-variables.html#global_page_variables and https://tlienart.github.io/JuDocWeb/pub/syntax/page-variables.html#rss)

Some code

So you may be aware that JuDoc allows for recursive parsing, i.e. you can have some Julia code within a markdown page which is executed at build time and whose output can be plugged back as generated markdown. This allows to have "for loops", see for instance: this example which can be used to build team cards where each card has the same style by looping over a list of names/bios.

While this may seem a bit convoluted, it's quite powerful once you get used to it. Below is one way of doing what I think you want. Note though that, as stated above, I'd like to support a clean way of getting a list of posts, possibly in chronological order which is what you may want; but it will take me some time to get there. In the mean time your feedback/thoughts on how you'd like this to be done would be very welcome

code

julia> newsite("tester")

Now if you write in index.md the following code, it will generate a list of links to all the pages. Of course this is very barebone and you could do something better/cleaner where you capture the first paragraph, style the result etc etc.

## List of pages
```julia:exlist
#hideall
path = JuDoc.PATHS[:folder]

function find_title(pg)
    content = read(pg, String)
    m = match(r"@def\s+title\s+=\s+\"(.*)?\"", content)
    if m === nothing
        m = match(r"(?:^|\n)#\s+(.*?)(?:\n|$)", content)
        m === nothing && return "Unknown title"
    end
    return m.captures[1]
end

println("~~~")
println("<ol>")
for (root, _, files) in walkdir("src/pages")
    for file in files
        md   = joinpath(root, file)
        html = replace(md, joinpath("src", "pages") => "pub")
        html = replace(html, r".md$" => ".html")

        t = find_title(md)
        l = JuDoc.unixify(html)
        println("<li><a href=\"$l\">$t</a></li>")
    end
end
println("</ol>")
println("~~~")

\textoutput{exlist}

gives:

<img width="497" alt="Screen Shot 2019-12-27 at 23 56 51" src="https://user-images.githubusercontent.com/10897531/71535214-a26ecd80-2904-11ea-8648-7668f9953931.png">

[Moelf]

Hi,

Thanks for the swift and detailed reply.

Are you referring to chronological posting? where you would have a page with an ordered list of all the posts?

yes exactly, since most blogs are probably intended to be posted from time to time, I can see that https://cormullion.github.io/ is using the sidebar as such, which is kinda janky.

I think a barebone functionality would be something like what hyde has -- list posts in rever time order and then have older, newer page flip at bottom.

JuDoc allows for recursive parsing

ah, I see, this is probably better than what I do at the moment (having a separate Julia script to generate index.md)

Again, thx for the work and reply, if I find a non-hacky workaround I may make a PR ;)

[tlienart]

I'll reopen to keep track to the reference to the cascading style.

With respect to the chronological posts, I've opened an issue more specifically for this here: https://github.com/tlienart/JuDoc.jl/issues/331

I think it won't take me too long to implement the basic stuff in JuDoc, it may take me a bit longer to test this on some simple layout like hyde, if successful I'll ping you for comments if you don't mind.

Cheers

[Moelf]

I re-realized we should probably leverage this from template engine Mustache, at least for front page geneation. https://github.com/jverzani/Mustache.jl#iteration

[tlienart]

Oh, nice, yes I'll have a look at what Mustache can do for us, that could be a neat integration

[Moelf]

slightly off-topic but I also think we can re-use Weave.jl for code evaluation if you render the code block with render("path to some .jmd", doctype="github") the following:

```julia
a = 2
println(a)

using Plots
histogram(randn(100))

a = 2
println(a)

2

using Plots
histogram(randn(100))

it for some reason uses four `, but I think it would let use re-invent less wheels.

[tlienart]

Thanks, the current code evaluation of JuDoc works fairly well and I use it extensively so I won't just remove it. However it could be nice for JuDoc to allow for a page to defer its parsing to Weave for people who want to use it (or may already have a tutorial written in .jmd) We could imagine something like:

@def useweave  =  true
...

And the whole page would then be processed by Weave and the resulting HTML plugged in. I'll think about it 😄

[Moelf]

what I like about Weave is that it doesn't create .jl files somewhere and has file-level separation in terms of evaluation (I think).

[tlienart]

Ok so that's all well and good if you want to work one page at the time and don't mind reevaluating it in full each time you modify it; this is similar to a notebook.

In JuDoc, files are created because it allows to avoid re-evaluating cells from pages that you don't modify. This may seem unnecessary if you only have one page with code, but if you have dozens (e.g. with MLJTutorials), you really don't want to do that.

No doubt you could do this better or some other way, but I don't think Weave solves that problem (afaiu).

Note that for instance a Jupyter notebook keeps track of the past evaluation inside the file, but at the end of the day that's not very different to creating a bunch of files in a dedicated repo 🤷‍♂ .

Edit: but if you just occasionally use code and it's very quick to evaluate, then doing what I suggested above i.e.: allow Weave for given pages, could be fine :)