├── .gitignore
├── README.md
├── cols.css
├── cols_macro.js
├── demo.Rmd
├── demo.html
├── eee-fonts.css
├── eee.css
├── libs
└── remark-css
│ └── default.css
└── xaringan_columns.Rproj
/.gitignore:
--------------------------------------------------------------------------------
1 | .Rproj.user
2 | .Rhistory
3 | .RData
4 | .Ruserdata
5 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Create Columns for Remark.js / xaringan
2 |
3 | This project contains a small JavaScript macro which can be used in Markdown for writing Remark.js or xaringan slides. The purpose of the macro is to allow users to easily create multiple-column slide layout.
4 |
5 | ## Contents
6 |
7 | The most important documents you will find here are:
8 |
9 | - `cols_macro.js`: contains actual `col_header`, `col_list`, and `col_row` macro code
10 | - `cols.css`: contains corresponding macro CSS - part **necessary** to make the macro work and part illustrating *optional* settings (e.g. coloring)
11 | - `demo.Rmd`: shows where and how to call these macros in a .Rmd file for a [`xaringan`](https://github.com/yihui/xaringan) presentation
12 | - `demo.html`: shows the output. It is also hosted on the corresponding [GitHub Pages](https://emilyriederer.github.io/xaringan_columns/demo.html)
13 |
14 | Other style sheets are simple are for personal design choices in my demo deck.
15 |
16 | ## How-To Use
17 |
18 | To use this macro, you would need to save `cols_macro.js` and `cols.css` in your project's directory. Then, reference these files in your YAML header. An example of this step is the YAML header of `demo.Rmd`:
19 |
20 | ```markdown
21 | ---
22 | title: "Macro for Many Columns"
23 | author: "Emily Riederer"
24 | output:
25 | xaringan::moon_reader:
26 | lib_dir: libs
27 | css: ["default", "eee.css", "eee-fonts.css", "cols.css", "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"]
28 | nature:
29 | beforeInit: "cols_macro.js"
30 | highlightStyle: github
31 | highlightLines: true
32 | countIncrementalSlides: false
33 | ---
34 | ```
35 |
36 | Observe that `cols.css` is in the `css:` key-value pair, and `cols_macro.js` is in the `beforeInit` key-value pair.
37 |
38 | ## Functionality
39 |
40 | `cols_macro.js` defines three macros that can be called in Markdown as follows:
41 |
42 | - `![:col_header x, y, z]`: creates header with CSS class `multicolhead` for styling
43 | - `![:col_list x, y, z]`: creates row of bulletted list items for each column
44 | - `![:col_row x, y, z]`: creates row of text for each column
45 |
46 | To create a three-column layout with a header row and lists, you might do something like this:
47 |
48 | ```markdown
49 | ![:col_header Header 1, Header 2, Header 3]
50 | ![:col_list item 1.1, item 2.1, item 3.1]
51 | ![:col_list item 1.2, item 2.2, item 3.2]
52 | ```
53 | where you would replace all "Header i" and "item i" with whatever text you want.
54 |
55 | ## A Note on Design
56 |
57 | This approach lets you build your columns row-by-row, similar to how you might think about laying things out in your head. As a result, it's implemented with a bunch `div`s. I considered alternatively having a single syntax with something like:
58 |
59 | ```
60 | ![:col_table dim1, dim2,
61 | h1, h2, h3,
62 | item 1.1, item 1.2, item 1.3]
63 | ```
64 |
65 | which could be implemented with `
` instead. However, the end-user syntax here seemed bulkier to me, and it seemed less in line with how I tend to be thinking and writing when I'm making this sort of layout, so I took with the former approach.
66 |
67 | ## Benefits
68 |
69 | My motivation for making this was that I'm trying to switch most of my personal/professional work to [`xaringan`](https://github.com/yihui/xaringan) and away from editors like Powerpoint. I knew to use this at work, someone was going to inevitably want a "three boxer", and I couldn't find a great existing way to do that.
70 |
71 | Relative to just laying things out in rows, columns can sometimes have advtanges in terms of emphasizing the parallel (versus sequential) nature of content.
72 |
73 | Relative to hard-coding an HTML table in my RMarkdown, this keeps my RMarkdown a lot more readable/writable by modularizing the code. Now, I don't have to be retyping/copying the same thing over and over or risk accidentally deleting something in a chunk of HTML code. Unfortunately, this means I do sacrifice something in the abilitiy for truly arbitrary custom styling.
74 |
75 | ## Pitfalls
76 |
77 | This is currently in total hack status as something I made quickly just to achieve a specific end results for a deck I was making. It worked fine for my purpose, but undoubtedly has rough edges.
78 |
79 | There are currently a number of known short-comings to this approach. I list them below, but they are better understoof via illustration in the [demo deck](https://emilyriederer.github.io/xaringan_columns/demo.html). Known issues are:
80 |
81 | - It can be hard to leave one column truly blank for a given row
82 | - Text in any cell can't contain commas or periods
83 |
84 | ## About Macros for `xaringan`
85 |
86 | This is a section I'm definitely not the right person to write. My inspiration/learning started from the [`xaringan` GitHub issue](https://github.com/yihui/xaringan/issues/80) on the topic.
87 |
--------------------------------------------------------------------------------
/cols.css:
--------------------------------------------------------------------------------
1 | /* Required: Clear floats after the columns */
2 | .multicolrow:after {
3 | content: "";
4 | display: table;
5 | clear: both;
6 | }
7 |
8 | /*Optional: Color header boxes*/
9 | .multicolhead {
10 | background-color:#4B9CD3;
11 | color: #FFFFFF;
12 | }
13 |
14 | .wordwrap {
15 | white-space: pre-wrap; /* CSS3 */
16 | white-space: -moz-pre-wrap; /* Firefox */
17 | white-space: -o-pre-wrap; /* Opera 7 */
18 | word-wrap: break-word; /* IE */
19 | }
20 |
21 | .multicolcol {
22 | min-height: 1px;
23 | }
24 |
--------------------------------------------------------------------------------
/cols_macro.js:
--------------------------------------------------------------------------------
1 | // creates equal-width column headers with css class multicolhead for styling
2 | // ...titles is a comma-separated list a values to determine number and contents of columns
3 |
4 | remark.macros.col_header = function (...titles) {
5 |
6 | var num_items = titles.length;
7 | var width = Math.floor(100/num_items) - 2*0.5;
8 |
9 | var code =
10 | '