possible rendering issue with nested lists?

[sbromberger]

See https://github.com/JuliaGraphs/LightGraphs.jl/blob/master/CONTRIBUTING.md - this is rendering as http://juliagraphs.github.io/LightGraphs.jl/latest/contributing/ - and if you scroll down to the "Development guidelines" section, you'll see that the list is not outdented after

PRs introducing dependencies on non-core non-leaf packages require strict scrutiny and will likely not be accepted without some compelling reason (urgent bugfix or much-needed functionality).

as it is in the markdown.

[MichaelHatherly]

Probably dup of #159. mkdocs and python-markdown doesn't appear to handle nested lists all that well.

[hayd]

I don't get this, the suggested issue/blame is Python-Markdown/markdown#3 (and mkdocs/mkdocs#545), it seems like python's markdown lib parses this file just fine.

[sbromberger]

I surrounded the nested list with whitespace but it didn't have any effect.

Just to be clear - nested lists do, in fact, nest - but they don't "un-nest".

[ChrisRackauckas]

FYI I've had a better experience with native HTML rendering does better with nested lists. If you check out my current page (switched to the native HTML rendering since that issue)

http://juliadiffeq.github.io/DifferentialEquations.jl/latest/

[emoszkowski]

Interesting - I'm having a similar issue but am using native HTML rendering. @ChrisRackauckas, is there some secret sauce you're using?

[ChrisRackauckas]

Nothing special. But it is really sensitive to the tab spacing of the next line for multiline text.

[bicycle1885]

I see the same problem on Bio.jl. Nested lists are broken after building docs.

docs/make.jl:

using Documenter, Bio

makedocs()
deploydocs(
    deps = Deps.pip("mkdocs", "pygments", "mkdocs-biojulia"),
    repo = "github.com/BioJulia/Bio.jl.git",
    julia = "0.5",
    osname = "linux",
)

docs/src/index.md:

Bio.jl provides programmable components for quick prototyping of new analyses
and algorithms. These components are carefully tuned to achieve the best
performance without sacrificing the usability of the dynamic programming
language. The following modules are currently part of the package and actively
developed as submodules:

* `Bio.Seq`: Biological sequences
    * Biological symbols (DNA, RNA and amino acid)
    * Biological sequences
    * Sequence search algorithms
    * Readers for FASTA, FASTQ and .2bit file formats
* `Bio.Align`: Sequence alignment
    * Alignment data structures
    * Pairwise alignment algorithms
    * Reader for SAM and BAM file formats
* `Bio.Intervals`: Genomic intervals and annotations
    * Genomic intervals with annotations
    * Readers for BED, BigBed and GFF3 file formats
* `Bio.Structure`: Molecular structures
    * Macromolecular structures (e.g. proteins)
    * Reader for PDB file format
* `Bio.Var`: Biological variation
    * Mutation counting
    * Genetic and evolutionary distances
    * Readers for VCF and BCF file formats
* `Bio.Phylo`: Phylogenetics
    * Phylogenetic trees
* `Bio.Services`: APIs to other services
    * Entrez utilities (E-utilities)

docs/build/index.md:

Bio.jl provides programmable components for quick prototyping of new analyses and algorithms. These components are carefully tuned to achieve the best performance without sacrificing the usability of the dynamic programming language. The following modules are currently part of the package and actively developed as submodules:


  * `Bio.Seq`: Biological sequences

      * Biological symbols (DNA, RNA and amino acid)
      * Biological sequences
      * Sequence search algorithms
      * Readers for FASTA, FASTQ and .2bit file formats
  * `Bio.Align`: Sequence alignment

      * Alignment data structures
      * Pairwise alignment algorithms
      * Reader for SAM and BAM file formats
  * `Bio.Intervals`: Genomic intervals and annotations

      * Genomic intervals with annotations
      * Readers for BED, BigBed and GFF3 file formats
  * `Bio.Structure`: Molecular structures

      * Macromolecular structures (e.g. proteins)
      * Reader for PDB file format
  * `Bio.Var`: Biological variation

      * Mutation counting
      * Genetic and evolutionary distances
      * Readers for VCF and BCF file formats
  * `Bio.Phylo`: Phylogenetics

      * Phylogenetic trees
  * `Bio.Services`: APIs to other services

      * Entrez utilities (E-utilities)

web browser:

[tkf]

I guess this because Documenter.jl (or stdlib Markdown?) produces "loose" Markdown while Python-Markdown used from mkdocs is very strict about the syntax.

Here is how Python-Markdown mentions about 4-space rule and nested list items:

• Indentation/Tab Length

  The syntax rules
  clearly state that when a list item consists of multiple paragraphs, "each
  subsequent paragraph in a list item must be indented by either 4 spaces
  or one tab" (emphasis added). However, many implementations do not enforce
  this rule and allow less than 4 spaces of indentation. The implementers of
  Python-Markdown consider it a bug to not enforce this rule.

--- https://python-markdown.github.io/#differences

However, Markdown generated by julia does not follow this rule:

julia> io = IOBuffer("""
       - a
           - b
           - c
       """);

julia> md = Markdown.parse(io)
    •    a

          •    b

          •    c



julia> println(md)
  * a

      * b
      * c

Notice that there are two spaces before * a and breaks the 4-space rule.

I didn't dig into Documenter.jl internals but I suppose it uses stdlib Markdown renderer internally? If so maybe it should be reported in Julia? Meanwhile, is it possible to fix this in Documenter.jl?

See also:

• Incorrect rendering of nested lists · Issue #545 · mkdocs/mkdocs
• Nested lists require 4 spaces of indent · Issue #3 · Python-Markdown/markdown
• Is the flavor of Markdown used a secret? · Issue #1385 · mkdocs/mkdocs

[odow]

I'm doing a triage of open documenter issues and closing issues that are stale. If I've made a mistake, please re-open

Closing because this seems like it was fixed at some point. Here's an example from the JuMP docs:

You do have to make sure that the indentation is correct. I think there are a few other related open issues, so if I see them on my travels I'll link to them.