[v0.3.0] list

[tlienart]

docs

• document \\
• document html entities and backslash escaping etc
• document single, double and triple backticks
• document indirect links (images and href) + that this [link text](https:://www.mozilla.org/ "Mozilla") is not supported (where the "Mozilla" bit should be the link title).
  • recommend not to use things that could clash with code so for instance, do not use [link][1] if there may be some place in your code with [1] otherwise both will be replaced and it'll be a mess. so either prefer inline links or use ids which don't clash.
• document that headers should only be defined via #... (also for TOC generation)
• indented code blocks, why fenced is better (risk of clashes with lists, doesn't have the eval possibility and somewhat less battle tested) but otherwise ok
• document differences if come from other ssg (see Jekyll/JuDoc compatibility comments #201 and the last comment)
• document use of lang local page variable for indented code blocks

think

• either brainstorm or document; if something like `[...]: blah` is found it will be replaced (as per indirect link processing) though it shouldn't be because it's part of a code block; maybe we can just assume that won't happen too much and could offer a toggle to only have inline links (so no delayed links) in which case this wouldn't happen.

done

• Allow and/or automatically replace indented code blocks #207 indented code block (via PR closes #207 through introduction of LR_INDENT tokens #217)
• showing error message when an eval'd block fails (PR Add error message in eval block (see #186) #187)
• headers are now links
• automatic table of contents via \toc or \tableofcontents (PR Toc3 #188)
  • docs
• major cleanup of the code (trying to make naming more consistent and less clunky, general cleaning up etc)
• added \\ as a way to force the introduction of a line skip, this can be useful in the context of inclusions etc (see Minor note: could use \figalt to add an "alt" cserteGT3/JuDocPlottest#1 for context)
• added fixes for backslashes in code environment etc (issue Backslash and escaping issues #205, PR Mdfix #209)
• html entities are now supported (issue HTML entities #206, PR Mdfix #209)
• better status messages for cleanpull (PR Add nicer status messages when something printed meanwhile #190) and adding the possibility to specify a commit message for publish (PR Add commitmsg kwarg for publish() #191, creds to @cserteGT3)
• added \textinput command (PR Fr193 #194)
  • docs
• added \tableinput command (PR WIP: inserting tables with \tableinput command #197, creds to @cserteGT3)
  • docs
• added support for double backticks (see issue Compatibility with standard Markdown: a more serious look #204 and PR support for double backticks and tests, see #204 #210)
• added support for indirect links and images (PR support for commonmark style links #214)
• new version for JuDocTemplates (0.2.4) with updated KaTeX and Highlight.js + proper chmod of files.

[asprionj]

The JuDoc site, generated with JuDoc, of course...?

[tlienart]

Of course 😄

[Invarianz]

I think it would be nice to have some kind of integration with .
Especially the feature to evaluate code on the fly and put the output directly onto the webpage is a nice feature. Since the evaluation of functions in Weave.jl can be switched off or on for code blocks (or globally), it would not clash with your general idea; to not make code evaluation default as it slows down site generation.
Right now if I want to add code to my personal webpage (resembling REPL input and output) I use Weave.jl as an intermediate step to evaluate a block, generate a markdown page, change the code block name from julia to julia-repl and paste it into my JuDoc page. I think it would easily be possible to automatize this.

Great site generator by the way! I did not find any static webpage generator yet that has so many features necessary and suitable for scientists out of the box.

[tlienart]

Great site generator by the way! I did not find any static webpage generator yet that has so many features necessary and suitable for scientists out of the box.

Thanks!!

With respect to Weave.jl, I think effectively the original reasoning was that I didn't want to step on Documenter's or Weave's playground and indeed there was the potential issue of slowing down page generation. (Btw I was not aware that you could block code evaluation with Weave, I really should take a closer look at that package).

Here's a proposal for something that could be done, feedback would be great:

Possible approach

This would effectively just be a simple way to automatise the existing approach:

1. find executable code blocks which could be marked as ```julia:script1
2. copy the content of these blocks to assets/scripts/page_name/ with name script1.jl, if the file already exists, check whether the content matches and replace it if it doesn't
3. unless we have {file was present && content unchanged && output file available}, run the script and capture its output
4. same input approach as the current one

So from the user perspective, the markdown would look like

A simple line of code
```julia:script1
println(exp(1im*pi))
```
which leads to
\input{output}{script1}

This would slow down the generation of the page but assuming that the code blocks are not super complicated it should still be pretty quick (and I guess for slow code blocks one could still use the other method if they wanted).

Thoughts?

[Invarianz]

I believe that this is a nice solution. If we could add in the options comparable to Weave.jl like eval=true/false or term=true/false to evaluate and/or make it resemble a REPL session it would be perfect.
One thing to think about is the folder naming. If one has a growing webpage (with several subfolders in src/) the scripts folder could very fast start to overflow with folders and incorporated scripts. I personally like the idea to keep assets folders in subfolders of your src/ tree. So in my case it looks a bit like this:

src/pages/
         |- physics.md
         |- julia.md
         |- assets/
         |        |- scripts/
         |        |         |- script1.jl
         |        |- infra/
         |        |       |- rndimg.png
         |- physics/
         |         |- cdw.md
         |         |- assets/
         |         |        |- scripts/
         |         |        |         |- script1.jl
         |         |        |- infra/
         |         |        |       |- cdw.png
etc.

At least for met this creates a logical ordering of the scripts and images with respect to the order of my webpage.
In that sense I am not sure if the "global" assets folder is even necessary except for the first landing page.

[Invarianz]

Another, seperate thing that I realised right now (since I started putting papers directly into the assets/ folders to organise them): I am not exactly sure about all the technical implications but wouldn't it make sense (at least for the live preview) to create softlinks in the assets/ folders in pub/ instead of copying the content over? I think this should give a significant perfomance increase when dealing with large files (big pdfs, images etc.).

[tlienart]

scripts eval

I've opened an issue to keep track of discussion: #152

assets in pub

I may have misunderstood your point but I'm guessing it may be related to the previous one: if you keep all auxiliary content in yourwebsite/assets/, it doesn't get copied over, and is available at username.github.io/assets/... for instance this file: https://tlienart.github.io/assets/csml/cvxopt/lsc-usc.svg.

Now if you put any non-markdown content in src/pages/... then it does indeed get copied over to pub/... (only once though, unless it gets changed). So it's true that if you had a massive PDF in src/pages/phys/massivePDF.pdf, in the initial pass it would get copied over to pub/pages/phys/massivePDF.pdf which could take time. But then I'd recommend just putting it once and for all in assets/phys/massivePDF.pdf in which case it never gets copied over.

This could be clarified in the docs, no doubt.

Thanks for the feedback!