Guide to creating widgets? #46

Open
jergason opened this Issue Jun 19, 2012 · 16 comments

Projects

None yet

4 participants

@jergason

Is there a guide to creating widgets? I can't really find anything, and the default github repo that you clone seems to only have config files in the widgets directory.

@plusjade
Member

@jergason, there is no official guide yet, sorry. However there is a lot of content on how widgets work in general here: http://ruhoh.com/usage/widgets/

The main premise is that widgets allow you to bundle HTML, javascripts, stylesheets, and configuration together as a widget. You'd want to do this so you can separate external website-ish functionality from your core content. Also it's a nice way for the community to share common widgets in a plug-n-play manner. I have this obsession with modularity so even though I think having a million configuration files is a little wonky, it really comes together nicely when you think about things being properly name-spaced and atomic.

Admittedly this is a bit of an over-engineered solution at the moment but I'm in it for the long haul ;)

After giving the usage docs a read, you'll want to look at the system level widgets as samples: https://github.com/ruhoh/ruhoh.rb/tree/master/widgets. You are correct in that these widgets do not appear in the default blog repo, only the config.yml is present. System level widgets work exactly like user-defined widgets so you can literally drop this in your repo and play with them to see how changes affect the widget. Note also that widgets cascade. user-defined widgets and their files will always override system level widgets and files of the same names.

Lastly you can check out the internal logic that powers widgets:

One more thing; I'll get some custom widgets I've made up as soon as possible so it will be more apparent on how/why to make and use them.

Thank you for your interest, please ask me as many questions as you want!

@jergason

Awesome, thanks. I think I'll try to put one together this week sometime.

Sent from my iPhone

On Jun 19, 2012, at 3:20, Jadereply@reply.github.com wrote:

@jergason, there is no official guide yet, sorry. However there is a lot of content on how widgets work in general here: http://ruhoh.com/usage/widgets/

The main premise is that widgets allow you to bundle HTML, javascripts, stylesheets, and configuration together as a widget. You'd want to do this so you can separate external website-ish functionality from your core content. Also it's a nice way for the community to share common widgets in a plug-n-play manner. I have this obsession with modularity so even though I think having a million configuration files is a little wonky, it really comes together nicely when you think about things being properly name-spaced and atomic.

Admittedly this is a bit of an over-engineered solution at the moment but I'm in it for the long haul ;)

After giving the usage docs a read, you'll want to look at the system level widgets as samples: https://github.com/ruhoh/ruhoh.rb/tree/master/widgets. You are correct in that these widgets do not appear in the default blog repo, only the config.yml is present. System level widgets work exactly like user-defined widgets so you can literally drop this in your repo and play with them to see how changes affect the widget. Note also that widgets cascade. user-defined widgets and their files will always override system level widgets and files of the same names.

Lastly you can check out the internal logic that powers widgets:

One more thing; I'll get some custom widgets I've made up as soon as possible so it will be more apparent on how/why to make and use them.

Thank you for your interest, please ask me as many questions as you want!


Reply to this email directly or view it on GitHub:
#46 (comment)

@dickfeynman

Hi, I'm trying to put together a ruhoh widget for MathJax. I don't know any Ruby, so bear with me.

The intended functionality of the widget is to insert a few lines of javascript into the html layout file. If I hardcode those lines of javascript into default.html inside the theme, then it works. Ideally, I would like the script added to pages and posts, but at least to posts. (Should I do anything to ensure this, or is it taken care of automatically?)

Now, the implementation. Is it enough if I create a layout/mathjax.html containing the javascript, and config.yml containing "layout : mathjax"? So far, I have created those files inside widget/math and added those 2 files to ruhoh.gemspec, and then compiled and installed the gem. But this doesn't seem to work. Wha am I missing?

@plusjade
Member

@dickfeynman so first off the widgets functionality is made entirely so you don't have to hack on the gem itself. The widget should work magically just by placing it in your blog's "widget" folder.

As for the implementation. Can you link me to a public repo where your code currently is? I'll try to run it locally and see if I can get it working. In general, widgets have the ability to register arbitrary javascript files for inclusion into the page. So that seems like pretty much all you need if i am understanding your correctly. The next main/important thing with Mathjax though, is how to have a formatter tag that will take a mathjax string and apply the syntax needed to label it as a Mathjax string -- this would be the harder problem.

Overall, I would love to help you get this working so ideally we can collaborate via GitHub =)

@ramnathv

I use mathjax in ruhoh by doing the following, and it works great for me. I presume you are missing the second step, and if I understand ruhoh correctly, you need that.

Create a mathjax widget

widgets
   mathjax
      layouts
          mathjax.html

Add it to the page/blog layout

{{{ mathjax }}}

UPDATE: My mathjax config is copied from stackexchange. This is what I have in my mathjax.html file

<!-- INSERT MATHJAX CONFIGURATION FROM MATH.STACKEXCHANGE -->
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  jax: ["input/TeX", "output/HTML-CSS"],
  tex2jax: {
    inlineMath: [ ['$', '$'] ],
    displayMath: [ ['$$', '$$']],
    processEscapes: true,
    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
  },
  messageStyle: "none",
  "HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"] }
});
</script>
<script type="text/javascript"
src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
@ramnathv

On a related note, if you can put together some guidelines for contributing widgets, that would be appreciated. I have put together a widget for highlight.js and works are in the process for a pygments widget. So if there are guidelines, I can stick to that rather than inventing my own.

Here is a link to my ruhoh blog (it is purely a playground currently, as i refine my quest for a good workflow) and source on github

@dickfeynman

Thanks, @plusjade and @ramnathv

@plusjade: Ah, okay. Since I saw the layout files for other default widgets in the ruhoh.rb source code, I got confused. For now, my javascript is quote similar to that of @ramnathv.

I didn't realize that I had to manually add {{{ widget-name }}} to themes/footheme/layouts/default.html. Now I have it working roughly. What's tripping up is that markdown is working on LaTeX aspects of the write-up (especially underscores). I wonder if there's a way to protect a block from being processed by markdown and simply pass it to the HTML file, to be taken care of by the javascript. I think this is what @plusjade alluded to.

Here is my ruhoh blog and the source code.

I've been reading a bit about how StackExchange sites manage to mix math with markdown.

  1. http://meta.stackoverflow.com/questions/12700/add-latex-support-to-markdown-wmd
  2. http://stackoverflow.com/questions/2188884/how-can-i-mix-latex-in-with-markdown

Ps: Since we're discussing how to implement MathJax support, should we shift this to a thread of it's own?

@plusjade
Member

@dickfeynman most early adopters of ruhoh really want the mathjax integration. I've played with a plugin but the hard part, as you mentioned is to get it working nicely with markdown. The most intuitive approach would probably be to add a custom markdown tag to the markdown engine. For now, one of the methods I was playing with was to override the back-tick functionality to support mathjax -- something like this:

<!-- inline -->
`mj:(x^{\*}, y^{\*})` 

<!-- block-->
'''mathjax                                # these are backticks but markdown is barfing on them
\dot{x} &= f(x, y) \newline
\dot{y} &= g(x, y) 
'''                                            # these are backticks but markdown is barfing on them

Forgive me if that syntax is not entirely correct, but the idea is just to treat mathjax like a type of code language. I don't personally use mathjax though so I really can't say what the best implementation would be. However I am in full agreement of supporting this natively and will open it up for discussion.

@dickfeynman

I would think that most people would prefer to write in LaTeX and have the javascrip convert that to MathJax (that's how it's usually done). For example, have a look at the source of the sample math page on my blog.

@ramnathv

I would not reinvent the wheel regarding mathjax syntax. The better approach would be to use a markdown converter that has the ability to leave mathjax alone. I believe RedCarpet2 has the option no_intra_emphasis which does not wrap underscores in <em> blocks. So is the case with kramdown.

Since ruhoh does not allow custom plugins, for now my approach is to use a custom markdown renderer and push the compiled site. However, it would be nice if ruhoh allows users to swap markdown converters easily ala jekyll style.

@plusjade
Member

Hmm, yeah that is what I find most people using. The main problem with that is the markdown parser is going to screw up those lines due to the underscores (dealt with this issue intimately with another guy trying to make it work). Now you can make it work easily if you use the mathjax js library style of enclosing them in script tags because markdown does not parse anything inside HTML tags. However writing more markup certainly is not the ideal answer.

I think it would be nice to extend the markdown library to support LaTeX blocks (honestly don't know how hard that would be) but for redcarpet specifically, it's actually just a wrapper for a C library so it is not easily extensible.

The next possible solution would be to employ a server-side LaTeX converter and pass files first through the LaTeX converter which wil wrap the necessary script tags around everything, and then hand that off to the markdown converter.

Thoughts?

@ramnathv

@plusjade as indicated earlier both kramdown and RedCarpet2 are easy to make workable with mathjax since they have the extensions that support mathjax. I dont think hacking on RedCarpet would be a good way to go about this.

@plusjade
Member

@ramnathv as far as I know I'm pretty sure ruhoh is already using redcarpet2. I'll push an update to enable : no_intra_emphasis. Also you can use whatever markdown parser you want via a custom plugin, unless you mean you'd like the ability to choose a markdown parser when pushing to http://username.ruhoh.com ?

@ramnathv

Yes. I meant for pushing to ruhoh.com. I use kramdown currently.

@dickfeynman

@plusjade Working on the LaTeX first and converting it to HTML (with something like tex4ht) before the markdown processing sounds like a plausible solution.

I'm not well versed with markdown, but it seems to me that markdown has no use for $ or $$. Can we have markdown (parsers) blindly pass everything that is (standard LaTeX syntax for math) $foo$ or $$foo$$? If used in conjunction with the MathJax javascript, that would be a decent start to using math on HTML pages written using markdown.

@ramnathv

@dickfeynman you don't need to look as far as tex4ht. Using RedCarpet2 extensions along with some Mathjax configuration should do the trick. I have used it successfully on Octopress which is another custom blogging tool.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment