What editor to use for MD files?

(Konstantin Polychronov) #1

Hi all,

recently I’ve had a short discussion in my pull request with Jerome Luckenbach, about putting HTML tags in the README.MD file and that it’s generally a bad idea. I do that because Eclipse formatter for Java is auto-formatting the MD file by cutting the ending spaces on each line which according to MD specs should stay for new line.

I wonder if you use different editor for the MD files or there is a way to setup special formatter?
Thanks in advance for any advices !


(Vincent Regaud) #2

I use VS Code with an md plug in: Markdown All in One

(Elias H.) #3

Since I use Emacs for almost everything… Emacs? :smiley:

(Hilbrand Bouwkamp) #4

You might be better of to use the Eclipse editor for this. Simple because the next committer might make a simple fix to your readme and use the Eclipse editor and all of your carefully cultivated spaces are gone. Maybe it’s something that should be changed in our Eclipse configuration. However spaces at the end with a meaning are probably not the best way to insert newlines anyway. This brings me to your readme. At the places you have used the newline tag you should use the table construction (with bars, |--|--|) That is the common way used in other binding readme files to show channels, options, etc. It’s better readable. On other places you need a newline put an empty line in between.

(Mark) #5

I agree with this, and this is what I’ve done in the READMEs for my bindings. My only beef with Eclipse is that the preview window does a terrible job rendering the markup. Maybe I’m missing something in my Eclipse config?

(Ben Clark) #6

I really like the side-by-side preview too.

As a user of VS-Code for openhab-linuxpkg and for my .rules editing, I’m eager to see the full-maven builds through openhab2-addons and openhab-core so I can stick with the one editor if I ever contribute elsewhere.

(Hilbrand Bouwkamp) #7

Yes it’s horrible. I always go to Github in such a case and open a readme file in edit mode (or just any readme file) online and look in preview mode to see the results. And then copy the files to my local file.

(Jerome Luckenbach) #8

Hey @polychronov,

Thanks for bringing this discussion into the community.
From what i read here you are not the only one struggling.

Personally i use vscode for editing markdown files.
Simply because i use it anyway for most of the stuff i do, since i have started using it for openHAB a while ago.

(Konstantin Polychronov) #9

Thanks everyone for the advices!

Thanks also for the patience as I’m coming from the enterprise world lacking any modern technologies and I lack experience with MD, git, maven and so on. Trying to catch up. :blush:

As a summary:

  • I’ll use the VSCode for the MD files in future
  • I will also use the formatting guidelines Hilbrand provided for new lines and also for options/items/channels, etc…

Best regards,