Razor layout, Markdown body?

jskeet commented 7 years ago

Using HTML in Markdown is slightly painful - if you have blank lines followed by indented HTML, they're treated as code, for example. Additionally, quite a lot of what I'd personally like to include code for would be in the layout rather than the body - and while this is planned for MDVE, it's not there yet.

How feasible would it be to load a layout in regular Razor, but then render the body of the view in Markdown? MDVE would still be responsible for finding the right Markdown file - and even the right layout file - to start with, but then ask Razor to render the layout, calling back into MDVE (possibly with a tag helper?) for the body.

I don't know much about the Razor details, and it may be infeasible or impractical, but it would be great if possible.

hishamco commented 7 years ago

Yep it's painful, but that's the limitation of the markdown itself, coz it doesn't support all the HTML tags. Regarding to use the Razor layout it's cool for a particular reason, nothing but this implies that we mixed up between a separated view engines. One more thing what I personally missed is using classes & styles in the markdown to give me the control of the output, I saw some ideas that solve them, but I'm this may not included in the CommonMark, which means that we need another abstraction layer to do the job

jskeet commented 7 years ago

I don't understand your second sentence, I'm afraid. It really feels like the sweet spot is where you can use "the best tool for the job" for each of layout and body separately... and for layout, Razor really is a better tool than Markdown.

I agree that richer classes/styles would be nice, but that's a somewhat separate issue.

hishamco commented 7 years ago

What I mean is the razor is cool, but I don't wanna mix both of the view engines, furthermore the layout is simple html content with .md extension, I'm not sure what is the advantage if we make the razor layout?

jskeet commented 7 years ago

The advantage is that Razor is designed to be good for HTML - and layout is almost entirely HTML, with very little content. Markdown is good for content with very little HTML.

"Simple html content with .md extension" does not work, as I found when I was porting my Noda Time code. If you include intended HTML and have line breaks for readability, e.g.

<html>
...
    <body>

        <div>
          Some stuff in the div
        </div>

    </body>
</html>

... then the div is interpreted as code, following the normal rules of Markdown.

In my layout page, there's basically no benefit to Markdown, and lots of benefit to HTML. For the body of the page, the content itself, the reverse is true.

hishamco commented 7 years ago

I see, we can eliminate the extra line breaks at runtime, because in reality this is helpful at development time not the runtime, so that's why many people use html minification BTW could you please point to the Noda Time code that you are working on, I will struggle to make everything work as it was

jskeet commented 7 years ago

Eliminating the line breaks would mean that we wouldn't be treating it as real Markdown - they might be intentional. But I still don't see why it's a good idea to force the layout to be in Markdown when Razor is just a better tool for that job.

The current site is generated in Jekyll: https://github.com/nodatime/nodatime/tree/master/www

hishamco commented 7 years ago

Eliminating the line breaks would mean that we wouldn't be treating it as real Markdown

Jon don't forget that the layout is pure HTML, and I used MarkdownPage to parse the metadata, hope you got my point. However I can escape using CommonMark in the layout page, in this way everything will work as expected without eliminating anything

jskeet commented 7 years ago

No, the layout isn't pure HTML. It's Markdown, and is being treated as Markdown. If you put **foo** in there, it will come out in bold.

The fact that it almost never needs to use Markdown is precisely why this feature request exists.

If the layout isn't meant to include Markdown, we shouldn't be running it through CommonMark at all. We should be able to put the body through CommonMark, and then replace {{body}} with that rendered Markdown.

That would then still leave the fact that we can't use code within the layout page, which is slightly annoying as I have common things like highlighting the current page within the menu bar, which could do with code. Razor would make this easy.

It's possible that if we have fundamental disagreements about the purposes here, it might be best for me to let you get on with building what you want to build, and I can probably do what I need with something a bit smaller, possibly as a tag helper or similar - I don't want to waste your time with feature requests which are useful for me but don't fit into your bigger picture.

hishamco commented 7 years ago

Yep it will render **foo** as foo, because it uses CommonMarkdown previously, so that's why I told you that we may ignore the markdown conversion in the layout page. Now i'm checking the Noda Time docs, to try build it on top of the MDVE, regarding the highlighting of the current page, I know it's a problem for me know because we don't support code yet, so that's why I was thinking from the beginning to use Roslyn Scripting APIs. I'm agree that Razor is the best tool for you because it already has a lot of features, but I will struggle to make this view engine rich to fit the suitable scenarios

jskeet commented 7 years ago

Okay - feel very free to use Noda Time as a sort of sample use case to work on, and I'll investigate whether I can use Razor but still keep the convenience of only having .md files which are automatically picked up - that's what I really love.

hishamco commented 7 years ago

One more thing why you are using the convention {version}/userguide I think it would be nice if you change it to userguide/{verion}, so you are no longer need to create the userguide folder on each release

jskeet commented 7 years ago

Because there's also the API that goes alongside the version. So links from the userguide to the api just need ../api/LocalDate.html (or whatever) rather than ../../api/1.0.x/LocalDate.html.

hishamco commented 7 years ago

@jskeet I ended up without using Razor with the help of handlebars.js, you can check the latest changes the mDocs repo, further more I worked on the Noda Time userguide the progress is very promising, nothing but I should do some tweaks to make everything work as it was, because the mDocs expect one documentation, but in your case there are many docs per version, also there 're some metadata such as weight, linkTitle will be removed, the latest updates will generate the menu and the navigation dynamically using a config.json

I will try to create a new Noda Time Docs repo, and share it with you, hopefully you will like it 😄

hishamco commented 7 years ago

@jskeet I already finished the first prototype of Noda Time docs on top of mDocs

jskeet commented 7 years ago

Thanks, I'll take a look - but there are tricky aspects such as the menu on the right of the user guide varying by version. (Ideally it should be autogenerated.)

I'm still going to have a look at alternative options, but I may well come back to MDVE for it :)

hishamco commented 7 years ago

Yep it's auto generated, but the one in the repo that you shared sub menus are dynamic, but the main menu items are static, so that's why the new menu is more dynamic than the previous one. I can add a new version to approve the point, if you have anything else to add please let me know. I'm glad to improve and build the Noda Time docs on top of markdown

hishamco commented 7 years ago

The only limitation on this that you need to add a config.json per version, in this case the problem solved. BTW almost the docs generation tools I ever seen generate a single docs, but in your case is different, so that why you need to tweak little bit to fit your needs

hishamco / MarkdownViewEngine

Razor layout, Markdown body? #8