PlutoStaticHTML

build_notebooks(
    bopts::BuildOptions,
    [files,]
    oopts::OutputOptions=OutputOptions();
    session=ServerSession()
)

Build Pluto notebook files in dir. Here, files is optional. When not passing files, then all Pluto notebooks in dir will be built.

Example

julia> dir = joinpath(homedir(), "my_project", "notebooks");

julia> bopts = BuildOptions(dir);

julia> oopts = OutputOptions(; append_build_context=true);

julia> files = ["pi.jl", "math.jl"];

julia> build_notebooks(bopts, files, oopts);

BuildOptions(
    dir::AbstractString;
    write_files::Bool=true,
    previous_dir::Union{Nothing,AbstractString}=nothing,
    output_format::Union{OutputFormat,Vector{OutputFormat}}=html_output,
    add_documenter_css::Bool=true,
    use_distributed::Bool=true,
    compiler_options::Union{Nothing,CompilerOptions}=nothing,
    max_concurrent_runs::Int=4
)

Arguments:

• dir: Directory in which the Pluto notebooks are stored.
• write_files: Write files to joinpath(dir, "$file.html").
• previous_dir::Union{Nothing,AbstractString}=Nothing: Use the output from the previous run as a cache to speed up running time. To use the cache, specify a directory previous_dir::AbstractString which contains HTML or Markdown files from a previous run. Specifically, files are expected to be at joinpath(previous_dir, "$file.html"). The output from the previous run may be embedded in a larger HTML or Markdown file. This package will extract the original output from the full file contents. By default, caching is disabled.
• output_format: What file to write the output to. By default this is html_output::OutputFormat meaning that the output of the HTML method is pure HTML. To generate Franklin, Documenter or PDF files, use respectively franklin_output, documenter_output or pdf_output. When BuildOptions.write_files == true and output_format == franklin_output or output_format == documenter_output, the output file has a ".md" extension instead of ".html". When BuildOptions.write_files == true and output_format == pdf_output, two output files are created with ".tex" and ".pdf" extensions.
• add_documenter_css whether to add a CSS style to the HTML when documenter_output=true.
• use_distributed: Whether to build the notebooks in different processes. By default, this is enabled just like in Pluto and the notebooks are build in parallel. The benefit of different processes is that things are more independent of each other. Unfortunately, the drawback is that compilation has to happen for each process. By setting this option to false, all notebooks are built sequentially in the same process which avoids recompilation. This is likely quicker in situations where there are few threads available such as GitHub Runners depending on the notebook contents. Beware that use_distributed=false will not work with Pluto's built-in package manager.
• compiler_options: Pluto.Configuration.CompilerOptions to be passed to Pluto. This can, for example, be useful to pass custom system images from PackageCompiler.jl.
• max_concurrent_runs: Maximum number of notebooks to evaluate concurrently when use_distributed=true. Note that each notebook starts in a different process and can start multiple threads, so don't set this number too high or the CPU might be busy switching tasks and not do any productive work.

OutputOptions(;
    code_class::AbstractString="language-julia",
    output_pre_class::AbstractString="code-output documenter-example-output",
    hide_code::Bool=false,
    hide_md_code::Bool=true,
    hide_md_def_code::Bool=true,
    add_state::Bool=true,
    append_build_context::Bool=false,
    show_output_above_code::Bool=false,
    replace_code_tabs::Bool=true,
    convert_admonitions::Bool=true
)

Arguments:

• code_class: HTML class for code. This is used by CSS and/or the syntax highlighter.
• output_pre_class: HTML class for <pre>.
• output_class: HTML class for output. This is used by CSS and/or the syntax highlighter.
• hide_code: Whether to omit all code blocks. Can be useful when readers are not interested in code at all.
• hide_md_code: Whether to omit all Markdown code blocks.
• hide_md_def_code: Whether to omit Franklin Markdown definition code blocks (blocks surrounded by +++).
• add_state: Whether to add a comment in HTML with the state of the input notebook. This state can be used for caching. Specifically, this state stores a checksum of the input notebook and the Julia version.
• append_build_context: Whether to append build context. When set to true, this adds information about the dependencies and Julia version. This is not executed via Pluto.jl's evaluation to avoid having to add extra dependencies to existing notebooks. Instead, this reads the manifest from the notebook file.
• show_output_above_code: Whether to show the output from the code above the code. Pluto.jl shows the output above the code by default; this package shows the output below the code by default. To show the output above the code, set show_output_above_code=true.
• replace_code_tabs: Replace tabs at the start of lines inside code blocks with spaces. This avoids inconsistent appearance of code blocks on web pages.
• convert_admonitions: Convert admonitions such as !!! note This is a note. from Pluto's HTML to Documenter's HTML. When this is enabled, the documenter_output has proper styling by default.