Rails 6 and Markdown Rendering - An Abject Personal Failure
source link: https://fuzzyblog.io/blog/rails/2019/10/19/rails-6-and-markdown-rendering-an-abject-failure.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Rails 6 and Markdown Rendering - An Abject Personal Failure
Oct 19, 2019
Note: I am not bitching here about the quality of Rails, High Voltage or any of the Markdown gems. This is all open source software and I am delighted to have the abundance of free tools available to me. And, trust me, I know that when people bitch, they should put on their big boy pants and contribute a pull request back to fix things. And, if I had been capable of fixing this, I would have. Alas I failed at fixing this.
Since I am a software engineer, I am experienced at failure. One of the absolutely soul diminishing aspects of being a software engineer that none of us talk about is that we fail. We fail a lot. Last night, for example, I spent about four hours in engaged in a soul crushing battle to get the High Voltage gem to work with Rails 6.
The High Voltage gem is a gem that lets you put a series of pages like about, support, faq, etc in a directory and it injects into your application a "pseudo controller" that handles the display. And then, if you aren't running Rails 6, you can add a markdown gem like kramdown-rails and then have a directory of files like about.md, faq.md and have these be part of your application. High voltage, along with a markdown gem, makes static pages an absolute delight.
And then came Rails 6. I put an alpha release of a side project live last night and my buddy Nick Janetakis helpfully clicked on the Faq link only to get a 500 error. "Oh yeah I commented, I've got an issue open on this". I checked the issue and even tho I reported it 24 days ago, it was lying fallow.
I figured, well, it is 2:30 in the morning and I had a craptacular night, why not dig into a complicated technical issue? I mean how hard can this be – it is just a pseudo controller, right? Well that was the beginning of a multiple hour session of low level gem debugging complete with a full round of Tourette's style cursing that I'm not real proud of but at least no one else was around.
Here are the branch names I created during this fiasco:
- markdown_bullshit_fucking_waste_of_time
- 294-anti-markdown
- 295-fuck-markdown-again
And here are some of the github issues I made:
- 295-fuck-markdown-again
- throw out fucking markdown insanity and rewrite pages into html erb
And I'd like to point out that no matter how pissed I got, I still followed good engineering practices:
- all code was always in a branch so I could always revert
- issues were created
- pull requests were used
Good engineering practices, when truly ingrained, when they are habits, carry you through bad experiences. Thank you Sean Kennedy for beating this into my head. Appreciated.
Things I Learned, Debugging and Otherwise
Here are some of the things I learned:
When you are doing gem debugging on osx and using TextMate, it is really, really helpful to open the gem in question with:
bundle show high_voltage
mate /Users/sjohnson/.rvm/gems/ruby-2.6.3/gems/high_voltage-3.1.2
This one, admittedly, I knew already but I always forget it when debugging gems. This opens the gem in a TextMate window with the full file tree of the gem available so you can add byebug calls freely.
After you add a byebug call to a gem, you have to start and stop the development server.
Not a one of the different markdown gems or techniques worked:
Rails 6 changed the render template call from 1 parameter to two parameter and I suspect that's at the heart of this.
And there were a few other things I tried. I got fairly close at the end but I kept getting Markdown issues and, ultimately, I felt it was wiser to just, well, stop.
My Final Solution
I ended up using the techniques that teamtreehouse advocated which amounted to:
- A simple pages controller
- A cool routing trick
And to make it easier for me, I added a dynamic index template which handles giving me a list of all static pages so I can easily review them. This was a dead simple (and mildy crappy) view but at this point I was about dead on my feet and I just wanted it done. Here's the view syntax:
<h1>Index</h1>
<ul>
<% Dir.entries(File.join(Rails.root, "app/views/pages")).sort.each do |file| %>
<% next if file =~ /^_/%>
<% next if file == 'index.html.erb'%>
<% next if file == '.'%>
<% next if file == '..'%>
<% filename = File.basename(file, ".html.erb")%>
<li><%=link_to(filename, "/pages/#{filename}")%>
<% end %>
</ul>
This could obviously be quite a bit better but this is one of those features that you write solely for yourself. It isn't linked to from anywhere on the site and the only one using it should be me or people on the project.
Conclusion
If you do this stuff long enough, you are bound to fail at things. I mean a software engineer's entire day basically amounts to "try stuff over and over and stop when it starts working". And, if you are lucky, then you get to take the time to make it better and maybe improve it. An embarrassingly large amount of the time that first working bit gets shipped.
Posted In: #rails
Recommend
-
33
TeXMe TeXMe is a lightweight JavaScript-based utility to create self-rendering Markdown + LaTeX documents. Note:If you are looking for a tool that renders only Markdown (no LaTeX), see ...
-
53
README.md TeXMe TeXMe is a lightweight JavaScript-based utility to create self-rendering Markdown + LaTeX documents.
-
45
README.md Down
-
21
TeXMe Demo Binomial Theorem $$ (x+y)^n = \sum_{k=0}^n {n \choose k} x^{n - k} y^k $$ Exponential Function $$ e^x = \lim_{n \to \infty} \left( 1+ \frac{x}{n} \right)^n $$ Cauch...
-
14
How to Build Rails views with Markdown Dec 28, 2016 So I'm starting prototyping on an all new thing and I it want to be commercially successful out of the gate. That's a bit different for me where I usually f...
-
4
Cryptocurrency is an abject disaster April 26, 2021 on Drew DeVault's blog This post is long overdue. Let’s get it over with. 🛑 Hey! I...
-
14
Free Software is an Abject Failureparitybit.ca Home Blog Links
-
6
Introducing NativeMarkKit, native Markdown rendering I’d like to announce the release of one of my side project...
-
3
A frequent question is, “Can I render Markdown files with Enhance?” and the answer is, “of course!” The Enhance documentation site is an Enhance app which renders markdown...
-
6
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK