Add snippet buttons for common AsciiDoc syntax, to help new users learn by doing.

[jsiu22]

So I couldn't find documentation for the syntax highlighting in the documentation files or in the hubpress knowledge base.

I realize after digging though the issues pages that you use.

[source,language]

---

Just thought it would be nice if this information was more accessible.

Also how do you choose which syntax highlighting style you want (highlight.js provides a lot of them I think.)

[jsiu22]

Actually I can't seem to get the highlighting part to work properly either. I made a test post here: https://jsiu22.github.io/blog/2017/02/28/Linux-Heredoc.html

Any ideas? Thanks!

[jaredmorgs]

Hmm, it may be theme-related why the highlighting is not being carried over into your post. Some themes have better code block syntax support, but I can't remember which ones they are.

@anthonny might remember which ones aren't so great for code-related blogs. If he can clarify which themes have better code block support, I can make a kbase entry.

I'd imagine that you have the following block in your code:

[source,bash]

tee /tmp/yourfilehere << EOF ...

As to the syntax help, we could put a terse code syntax example in the in-app help.

Code blocks are extensively documented in the Asciidoctor User Guide, which should be the canonical reference for any blogger writing with HubPress. --

Sent from Mobile.

[jsiu22]

Yea I noticed the Asciidoctor User Guide a few hours after that! Thank you.

Also that is pretty much the block I included in my post. Thanks for the follow up. Hope Anthonny can get back to us soon about the syntax highlighting. I mean it's obviously doing something (and giving classes correctly) just no colors.

I've been really liking the project so far by the way! Great work.

[jsiu22]

I had a few thoughts tho using the application. It would be nice to have line numbering, more modular highlight.js (for updating). Also instead of documentation it would be valuable to have buttons that generate a small skeleton for things users are trying to achieve.

I mean if = Title is required, why not just have it as a default in the editor, or a button to add the tag for images or something like that.

Just a thought, I know it's much more difficult to make but UI wise it makes sense. At least in the future when there are less important issues at hand to allow for more usability / polish.

[jaredmorgs]

I've always liked the idea of code snippets as well. I remember talking with @anthonny about this a long time ago. I also seem to remember Anthonny and I talking about having a way of inserting a default template with a button click, if the user wanted it.

The idea with that block that is auto-inserted into a new post is to un-comment the parts you need.

I understand what you mean about putting mandatory elements in. If we can template that, we could template a basic Blog header with appropriate replaceable text. --

Sent from Mobile.

[jsiu22]

Yea that just make sense from a UX perspective. This would definitely help the learning curve for new users (and be a convenience factor for other users).

I mean the Asciidoctor User Guide is great, but it's pretty dense.

I think it would be easier to provide more post samples for users to digest. (I've been peeking at other peoples post code heh).

This is really just coming from the perspective of a new user tho. It's not really that hard to figure out, but I just feel like the convenience factor would be appreciated by other new users.

[jaredmorgs]

As a product owner, understanding first-run user experience is really important. So thanks for the insights.

One challenging thing with adding snippet buttons into an interface is working out what will happen when a user loads HubPress on mobile, with a limited viewport. Where do the buttons go? Do you hide them in a menu and show them as a hover tip on click? There are so many approaches.

The good thing is that we can do a bit of a/b testing on the approaches and see which ones work.

I've used the same approaches as you have when trying to learn AsciiDoc. I think I would have lurked in the Asciidoctor community for a year before I felt confident enough to check out their docs repo and start fixing bugs. It can be overwhelming.

[jsiu22]

I totally understand. Thanks for being so on top of communication.