Fixes (#228)

* fixes to headers and toc and internal links

* fixes for JDINSERT followed by line return

* fixes for plain code blocks

* fixed a problem with overlapping defs global and local; global must take precedence

* more stuff

README.md

@@ -13,6 +13,7 @@ A couple of websites using JuDoc:
 * [@cormullion's website](https://cormullion.github.io), the author of [Luxor.jl](https://github.com/JuliaGraphics/Luxor.jl),
 * [my website](https://tlienart.github.io).
 * see also how [some julia blog posts](https://tlienart.github.io/julia-blog-migration/) render with JuDoc (note: _focus on the rendering, not the layout/CSS_) see also [the source repo](https://github.com/tlienart/julia-blog-migration).
+  * actually see [all of them](https://julialangblogmirror.netlify.com/) rendered with JuDoc thanks to massive help from [@cormullion](https://github.com/cormullion); see also the [source repo](https://github.com/cormullion/julialangblog)
 
 ### Key features
 

src/JuDoc.jl

@@ -24,6 +24,9 @@ const BIG_INT = typemax(Int)
 """Flag for debug mode."""
 const DEBUG_MODE = Ref(false)
 
+"""Flag for error suppression mode (set and unset in optimize only)."""
+const SUPPRESS_ERR = Ref(false)
+
 """Dict to keep track of languages and how comments are indicated and their extensions."""
 const CODE_LANG = Dict{String,NTuple{2,String}}(
     "c"          => (".c",    "//"),

src/manager/file_utils.jl

@@ -90,9 +90,9 @@ function process_file(case::Symbol, fpair::Pair{String,String}, args...; kwargs.
         DEBUG_MODE[] && throw(err)
         rp = fpair.first
         rp = rp[end-min(20, length(rp))+1 : end]
-        println("\n... error processing '$(fpair.second)' in ...$rp.")
+        println("\n... encountered an issue processing '$(fpair.second)' in ...$rp.")
         println("Verify, then start judoc again...\n")
-        @show err
+        SUPPRESS_ERR[] || @show err
         return -1
     end
     return 0

src/manager/judoc.jl

@@ -15,7 +15,8 @@ Keyword arguments:
                      of a project website, see [`write_page`](@ref).
 """
 function serve(; clear::Bool=true, verb::Bool=false, port::Int=8000, single::Bool=false,
-                 prerender::Bool=false, nomess::Bool=false, isoptim::Bool=false
+                 prerender::Bool=false, nomess::Bool=false, isoptim::Bool=false,
+                 no_fail_prerender::Bool=true
                  )::Union{Nothing,Int}
     # set the global path
     FOLDER_PATH[] = pwd()
@@ -36,7 +37,8 @@ function serve(; clear::Bool=true, verb::Bool=false, port::Int=8000, single::Boo
     # do a first full pass
     nomess || println("→ Initial full pass... ")
     start = time()
-    sig = jd_fullpass(watched_files; clear=clear, verb=verb, prerender=prerender, isoptim=isoptim)
+    sig = jd_fullpass(watched_files; clear=clear, verb=verb, prerender=prerender,
+                      isoptim=isoptim, no_fail_prerender=no_fail_prerender)
     sig < 0 && return sig
     fmsg = rpad("✔ full pass...", 40)
     verb && (println(""); print(fmsg); print_final(fmsg, start); println(""))
@@ -97,11 +99,14 @@ A single full pass of judoc looking at all watched files and processing them as
 * `clear=false`:     whether to remove any existing output directory
 * `verb=false`:      whether to display messages
 * `prerender=false`: whether to prerender katex and code blocks
+* `isoptim=false`  : whether it's an optimization pass
+* `no_fail_prerender=true`: whether to skip if a prerendering goes wrong in which case don't prerender
 
 See also [`jd_loop`](@ref), [`serve`](@ref) and [`publish`](@ref).
 """
 function jd_fullpass(watched_files::NamedTuple; clear::Bool=false, verb::Bool=false,
-                     prerender::Bool=false, isoptim::Bool=false)::Int
+                     prerender::Bool=false, isoptim::Bool=false, no_fail_prerender::Bool=true
+                     )::Int
      # initiate page segments
      head    = read(joinpath(PATHS[:src_html], "head.html"), String)
      pg_foot = read(joinpath(PATHS[:src_html], "page_foot.html"), String)
@@ -127,19 +132,34 @@ function jd_fullpass(watched_files::NamedTuple; clear::Bool=false, verb::Bool=fa
     s = 0
     begin
         if isfile(joinpath(indexmd...))
-            s += process_file(:md, indexmd, head, pg_foot, foot; clear=clear,
+            a = process_file(:md, indexmd, head, pg_foot, foot; clear=clear,
                               prerender=prerender, isoptim=isoptim)
+            if a < 0 && prerender && no_fail_prerender
+                process_file(:md, indexmd, head, pg_foot, foot; clear=clear,
+                              prerender=false, isoptim=isoptim)
+            end
+            s += a
         elseif isfile(joinpath(indexhtml...))
-            s += process_file(:html, indexhtml, head, pg_foot, foot; clear=clear,
+            a = process_file(:html, indexhtml, head, pg_foot, foot; clear=clear,
                               prerender=prerender, isoptim=isoptim)
+            if a < 0 && prerender && no_fail_prerender
+                process_file(:html, indexhtml, head, pg_foot, foot; clear=clear,
+                              prerender=false, isoptim=isoptim)
+            end
+            s += a
         else
             @warn "I didn't find an index.[md|html], there should be one. Ignoring."
         end
         # process rest of the files
         for (case, dict) ∈ pairs(watched_files), (fpair, t) ∈ dict
             occursin("index.", fpair.second) && continue
-            s += process_file(case, fpair, head, pg_foot, foot, t; clear=clear,
+            a = process_file(case, fpair, head, pg_foot, foot, t; clear=clear,
                               prerender=prerender, isoptim=isoptim)
+            if a < 0 && prerender && no_fail_prerender
+                process_file(case, fpair, head, pg_foot, foot, t; clear=clear,
+                                  prerender=false, isoptim=isoptim)
+            end
+            s += a
         end
     end
     # return -1 if any page

src/manager/post_processing.jl

@@ -14,7 +14,9 @@ Note: if the prerendering is set to `true`, the minification will take longer as
 will be larger (especially if you have lots of maths on pages).
 """
 function optimize(; prerender::Bool=true, minify::Bool=true, sig::Bool=false,
-                    prepath::String="")::Union{Nothing,Bool}
+                    prepath::String="", no_fail_prerender::Bool=true,
+                    suppress_errors::Bool=true)::Union{Nothing,Bool}
+    suppress_errors && (SUPPRESS_ERR[] = true)
     #
     # Prerendering
     #
@@ -35,13 +37,13 @@ function optimize(; prerender::Bool=true, minify::Bool=true, sig::Bool=false,
     print(fmsg)
     withpre = fmsg * ifelse(prerender, rpad(" (with pre-rendering)", 24), rpad(" (no pre-rendering)", 24))
     print(withpre)
-    succ = (serve(single=true, prerender=prerender, nomess=true, isoptim=true) === nothing)
+    succ = (serve(single=true, prerender=prerender, nomess=true, isoptim=true, no_fail_prerender=no_fail_prerender) === nothing)
     print_final(withpre, start)
 
     #
     # Minification
     #
-    if minify && succ
+    if minify && (succ || no_fail_prerender)
         if JD_CAN_MINIFY
             start = time()
             mmsg = rpad("→ Minifying *.[html|css] files...", 35)
@@ -58,6 +60,7 @@ function optimize(; prerender::Bool=true, minify::Bool=true, sig::Bool=false,
                   "The output will not be minified."
         end
     end
+    SUPPRESS_ERR[] = false
     return ifelse(sig, succ, nothing)
 end