Formatting goes haywire with a minor change to text

[aviramvijh]

Hi Slate team and @lord

Thank you for this wonderful tool, which suits my needs very well. I am running into some formatting issues that occur when I make even minor changes to different parts of my content. Sometimes the heading 2 (##) alignment goes for a toss, or sometimes the contents of a table are all boldfaced. As a result, I am having to save and preview each change I make to prevent spoiling something that previously worked well. Something very similar to what used to happen with MS Word in the early days...change one bullet list and the whole document's indentation went for a toss. FYI: I am previewing changes on http://localhost:4567 as I make them.

Specific examples of the problems with images:

The first image shows when things were OK. I only changed the text below Return a user, but the Path Parameters table went for a toss (everything got bold faced) and misaligned, as shown in the second.

The first image shows when everything was alright. I only changed the text below Return all user, but the Path Parameters heading got misaligned and also lost its correct formatting as shown in the second image.

Similarly, issue 3 shows both the HTTP Request heading misaligned and misformated and the Path Parameters table having the bold face problem as well.

I am cent perfect certain I am not introducing any errors while making the changes. Sometimes, even one character breaks the rendering. Sometimes I undo the changes, type the same thing manually, and it works, but sometimes it doesn't. The errors are very random :(

Please help me fix this problem :) Happy to provide any additional information.

Aviram

[aviramvijh]

@lord Please have a look at this if you can. Any one else is also welcome to pitch in!

[lord]

Sorry! This issue slipped though.

Hmm...could you post a Gist of a .md file that has errors sometimes? It'd also be helpful if you could inspect the HTML of a page with errors and the HTML of a page without, to see if any sort of weird HTML is being generated.

[aviramvijh]

@lord Thanks for your response. You are right, the HTML is where the problem lies...some sort of rendering issue when MD is converted to HTML. The problems are very random and can occur even when I change a letter, and more frequently occur when I use a previous section as a template to create a new one (like in the attached Gist file). The topic/heading that goes haywire seems to be automatically wrapped in double quotes. One example is in image 1..its very hard to consistently reproduce the problems...sometimes they get resolved if I change some other random content elsewhere! I am certain that the MD syntax is not where the issue is, because sometimes the issues appear in different even when I change a character of content like explained in my original post.

Similarly, the second image below replicates another such issue (similar to the second image of my original post), the Body Parameters are wrapped in double quotes instead of an h3 tag. This was working fine till I added a new section in the markdown file (Presence ...when you see the Gist. When I remove Presence, this error disappears, but some others don't).

Image 1:

Image 2:

The Gist file you requested is here: https://gist.github.com/aviramvijh/b4d12bba074f2ff8e923

[yukkyyuk]

I have exactly the same problem.

[aviramvijh]

@lord Any update will be very appreciated.

[lord]

@aviramvijh Any chance you could try again on the update branch after running bundle install? master is on a pretty old & funky version of RedCarpet.

[aviramvijh]

@lord Thanks for your response. I tried it with the updated branch but the problem persists :(

[filipw]

I have the exact same problem, I can't generate the docs correctly as always one of the h3 is messed up.

See this screenshot:

And corresponding markdown (which seems correct to me, doesn't it?)

     ## POST api/Values

     > Sample requests

     ```json
     {
       "Id": 1,
       "Foo": "sample string 2"
     }

 ```xml
 <MyModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/BasicWebApi.Controllers">
   <Foo>sample string 2</Foo>
   <Id>1</Id>
 </MyModel>
 ```

 ### HTTP Request

 `POST api/Values`

 ### Body Parameters

 Some crazy model

 Parameter | Required | Type | Description
 --------- | -------- | ---- | -----------
 Id | True | Int32 | Id of MyModel
 Foo | False | String | Foo of MyModel

[filipw]

and, similarly to what others reported, the HTML has plain text rather than the expected h3 tag

[filipw]

BTW, I was able to work around it by replacing ## and ### with <h2> and <h3> in the markdown file, but clearly there seems to be some issue in how these two headers are parsed when using hash.

[aviramvijh]

Wow, thanks @filipw . However, even if this works, certain other problems such as the one shown in the last image of my first post (where things get bold faced) won't be solved. @lord please take note of this. I'll post feedback soon.

[lord]

Hmm, this is such an odd bug. I can't replicate the weird markdown errors at all with the samples you've provided. I wonder if this is due to a RedCarpet bug specific to some weird thing on your computer — maybe some sort of weird configuration, or a memory-related bug in RedCarpet. As far as I can tell, it's not a bug with Slate, since we don't do anything special with the Markdown to HTML conversion any more.

A couple more questions, if you wouldn't mind helping me drill down a little more:

1. Are the errors consistent? That is, if you rebuild the same markdown multiple times, you always see the error? And if you change it to something else, and then back, does the error come back?
2. @filipw, if you run the markdown file provided by @aviramvijh, do you see the same errors that they do?
3. If you create a new Middleman project with cd ~/Desktop; middleman init test; cd test;, create a file source/test.md, fill it with one of your broken markdown files, run the server with middleman and visit http://localhost/test.html, do you see the HTML you'd expect, or do you see the bugs there too?

[filipw]

Looks like this happens only on Windows. My original issues all occurred when running on Windows. Using same file on OS X creates the HTML correctly without any issues at all times.

Guess shouldn't have used Windows :smile:

[aviramvijh]

@filipw @lord I was just about to mention that I suspect this might the problem. However, a slightly tricky question I have, and Lord can probably answer it, is whether these issues would then disappear when we eventually publish the pages to the web (externally)....because that wouldn't have anything to do with Windows/Mac?

[lord]

Aha! Yes, we don't support Windows unfortunately. I'd suggest using the Dockerfile, which should build Slate correctly.

The issues will actually still be there, since when you publish, the thing that converts the Markdown to HTML runs on your computer, and uploads raw HTML to Github. :confused: Sorry.

I'm going to close this since it seems to be just a Windows thing, but feel free to continue discussing!

[aviramvijh]

Thanks guys for your help.

[6stringbeliever]

I also ran into this problem while trying to get Slate working on Windows. I ended up just switching out RedCarpet for Kramdown. Kramdown is the default markup processor in middleman, anyway, so all you have to do is comment out the markdown lines in config.rb. The syntax for code blocks is slightly different in Kramdown (use ~~~ ruby instead of ```ruby). Otherwise everything seems to be working perfectly, so far.

Hope this is helpful to any poor souls stuck on Windows who come across this problem.