Hello all, an experience report follows, maybe it helps you guys make a decision. We held a SWC workshop recently at CERN and created material for two more days of training afterwards specific to LHCb (we all work at the Large Hadron Collider at CERN).
As none of us had ever done anything like that before we started from the lesson-template and followed the "if we need to decide something the default is to follow the recommendation in the template". This served us very well. One of the few things where we departed was having to build html locally and check it in. It was tedious and people kept forgetting to do it, diffs were huge, etc We setup Travis CI to do all the dirty work for us and it works extremely well. The automatic running of `make check` on every PR is especially useful. The repo is here https://github.com/lhcb/first-analysis-steps and the output here: https://lhcb.github.io/first-analysis-steps/ Setting up Travis was simple (Ok, we had someone who used travis previously) and so far we haven't found a downside yet. Hope this injects some data into the discussion. T On Fri, Jun 26, 2015 at 12:14 AM Carl Boettiger <[email protected]> wrote: > Not advocating for or against moving to Jekyll here, but I think Greg's > comment about trailing styles highlights another issue. tl;dr use redcarpet > instead of kramdown. > > If we tell people they can "use markdown" they probably think > Github-flavored markdown, e.g. that they write fenced code blocks with > language indicated: > > ```python > import matplotlib > ``` > > which is identical to pandoc, and thus familiar to RStudio users and all > existing lessons in pandoc. I suspect users will be surprised to learn > this doesn't work in Jekyll kramdown. Most users Googling syntax > highlighting in Jekyll will find things saying they should not put code in > markdown at all, but use Jekyll's Liquid format [1], like so: > > {% highlight python %} > import matplotlib > {% endhighlight %} > > Further confusing things. Least obvious might be the solution of > "trailing styles" > > ~~~ > import matplotlib > ~~~ > {: .language-ruby} > > > Is that really what we want? I realize Jekyll is now an independent > community project from GitHub with some historical legacy issues, but I > have no idea why it continues to default to a syntax that is so divergent > from Github's own markdown style. Anyway, I would suggest we at least use > redcarpet as the parser so that the code block notation we have been using > in pandoc, Github, etc continues to work. Trying to patch all knitr and > these other tools to use trailing styles does not seem consistent with the > goal of using familiar out-of-the-box tools. > > Cheers, > > Carl > > > [1]: http://jekyllrb.com/docs/templates/#code-snippet-highlighting > > > > On Thu, Jun 25, 2015 at 10:38 AM Doug Latornell <[email protected]> > wrote: > >> On Thu, Jun 25, 2015 at 10:14 AM Raniere Silva <[email protected]> >> wrote: >> ... >> >>> 6. The workflow for creating and publishing lessons >>> should be authentic, i.e., the way people write and >>> publish lessons should be a way they might use to >>> write and publish research papers. >>> >>> I want to have real data for this but I don't have. >>> >> >> I'm not sure if this qualifies as real data or not - it's not a research >> paper - but I recently re-mixed the present pandoc workflow, the hg-novice >> lesson content, and SWC layout to produce a full-day version control >> workshop for the Canadian MEOPAR Network of Centres of Excellence ( >> meopar.ca). Content is at < >> http://douglatornell.ca/training/meopeers-2015-06-15/> and repo is at < >> https://bitbucket.org/43ravens/meopeers-2015-06-15>. I would still have >> re-mixed the lesson content, but I doubt that I would have used the >> workflow if it had been jeykll/kramdown/gh-pages, and having to create a >> different workflow would have cost me a bunch more time. I see value in the >> more generic pandoc workflow. >> >> >>> What I know is that >>> (1) RStudio users have Pandoc off-the-shelf, >>> and are using it, >>> (2) IPython/Jupyter Notebook users are using Jinja2 >>> that is something that we will not considere using, >>> and (3) despite many people hate DOCX and ODT >>> many publishers still require it, >>> Pandoc can convert Markdown to DOCX/ODT >>> but Kramdown can't. >>> >>> Trying to be rational here, >>> Pandoc only loses in the GitHub Pages magic >>> so we should stay it it and replace GitHub Pages >>> for the lessons with another solution. >>> >>> If people really want to back to Jekyll >>> just because of GitHub I'm OK with it. >>> >>> Cheers, >>> Raniere >>> _______________________________________________ >>> Discuss mailing list >>> [email protected] >>> >>> http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org >> >> _______________________________________________ >> Discuss mailing list >> [email protected] >> >> http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org > > -- > > http://carlboettiger.info > _______________________________________________ > Discuss mailing list > [email protected] > > http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
_______________________________________________ Discuss mailing list [email protected] http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
