possible rendering issue with nested lists?

sbromberger commented 8 years ago

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 commented 8 years ago

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

hayd commented 8 years ago

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

sbromberger commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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

ChrisRackauckas commented 8 years ago

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

bicycle1885 commented 7 years ago

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: screen shot 2017-05-07 at 17 32 20

tkf commented 6 years ago

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?

JuliaDocs / Documenter.jl

possible rendering issue with nested lists? #261