Razor layout, Markdown body? #8
Comments
|
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. |
|
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. |
|
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? |
|
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. ... then the 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. |
|
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 |
|
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 |
Jon don't forget that the layout is pure HTML, and I used |
|
No, the layout isn't pure HTML. It's Markdown, and is being treated as Markdown. If you put 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 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. |
|
Yep it will render |
|
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. |
|
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 |
|
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. |
|
@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 😄 |
|
@jskeet I already finished the first prototype of Noda Time docs on top of mDocs |
|
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 :) |
|
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. |
|
The only limitation on this that you need to add a config.json per version, in this case the problem solved. |
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.
The text was updated successfully, but these errors were encountered: