Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Convert docs pages with tables to textile format #843

Closed
wants to merge 4 commits into from

5 participants

@cobyism

Yesterdaty @parkr and I discussed the way documentation pages in the new site containing tables currently require inline HTML for the tables (Markdown doesn’t have support for a table syntax). This isn’t as easy to maintain as it could be, so this PR will convert all docs pages containing tables over from .md to .textile, and switch to using Textile’s table syntax instead of inline HTML. It’s not ideal to have some docs pages written in markdown, and others in textile, but hopefully this should at least make it easier to maintain the documentation over time. Maybe downstream it would be worth also converting the rest of the docs (back) to textile so it’s all in a consistent format (I originally ported the docs to markdown when I pulled them out of the wiki—maybe that wasn’t a great idea?)

:construction: At the moment only the "structure" docs page is converted over, the rest will come :soon:. There’s probably also going to be some more CSS tweaking needed given the textile table output doesn’t contain some things the original styles expected like <thead>, and <tbody> elements, and <p> tags inside the table cells… All in good time :grin:

@parkr
Owner

Thanks for your work on this :thumbsup:

@cobyism

No worries—glad to be able to help out! :grinning:

@mattr-
Owner

Perhaps I'm just an old curmudgeon, but I don't actually see anything wrong with the inline HTML in the markdown file. IMHO, it's actually easier to read and understand than Textile's table syntax. How is inline HTML not as easy to maintain? Perhaps somebody could explain it to me like I'm five? :smile:

@cobyism

@mattr- There’s nothing really wrong with it per-se—in fact I originally converted the old wiki content from this textile format to markdown for the exact same reasons you just described. In terms of maintainability though, it’s a lot of extra markup to have to proof-read any time rows are added or removed from a table.

As an example, instead of having to add:

<tr>
  <td>
    <p><code>variable</code></p>
  </td>
  <td>
    <p>Description of the variable goes here.</p>
  </td>
</tr>

… it’s much less code to maintain to just write:

| @variable@ | Description of the variable goes here. |

It’s a pretty subjective call, but in my experience the more code there is to maintain, the more prone it is to errors—so I think using textile for the tables here is a net win. Also, if someone wants to contribute to the documentation but doesn’t know HTML, the textile table syntax is undoubtedly more approachable than inline HTML.

@mattr-
Owner

Thanks for the explanation! I'm convinced. :+1:

@mojombo
Owner

Man, I hate Textile with a passion, and mixing docs formats feels really wrong to me. I don't really see enough benefit here to warrant the change. I actually like the HTML version better, in that it can be nicely formatted to fit within an 80px wide file. I'm :thumbsdown: on this one.

@cobyism

@mojombo I have no idea how you code in an 80px wide editor :trollface:, but I take your points (and the editor-wrap factor hadn’t occurred to me, since I mostly have soft-wrap turned on by default). I’mma close this, but leave the branch around in case @parkr wants to reopen with any counter-points :smile:

@cobyism cobyism closed this
@parkr
Owner

Ideal solution: write a spec for tables in Markdown. @mojombo, that'll be right up your alley :wink:

@ixti

@cobyism I believe @mojombo mean 80 chars width. Usually such code is much easier to read. And most of the times lines with more than 80 chars contain "code smells".

I agree with @mojombo about properly "beautified" HTML tables. And would like to add that in fact diffs for such tables are easier to read as you can see diff of exact column that was changed, rather than full row.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 7, 2013
  1. @cobyism

    swap structure.md to textile

    cobyism authored
  2. @cobyism
  3. @cobyism
  4. @cobyism

    make min-height for articles tall enough for the lowest pages

    cobyism authored
    the arrow provided by the `.current` class didn’t have a page on its
    left to attach to, which made it look silly.
This page is out of date. Refresh to see the latest.
View
95 site/_posts/2012-07-01-structure.md
@@ -1,95 +0,0 @@
----
-layout: docs
-title: Directory structure
-prev_section: usage
-next_section: configuration
----
-
-Jekyll at its core is a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed on the layout and more. This is all done through strictly editing files, and the web interface is the final product.
-
-A basic Jekyll site usually looks something like this:
-
-{% highlight bash %}
-.
-├── _config.yml
-├── _includes
-| ├── footer.html
-| └── header.html
-├── _layouts
-| ├── default.html
-| └── post.html
-├── _posts
-| ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
-| └── 2009-04-26-barcamp-boston-4-roundup.textile
-├── _site
-└── index.html
-{% endhighlight %}
-
-An overview of what each of these does:
-
-<table>
- <thead>
- <tr>
- <th>File / Directory</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>
- <p><code>_config.yml</code></p>
- </td>
- <td>
- <p>Stores <a href="../configuration">configuration</a> data. A majority of these options can be specified from the command line executable but it’s easier to throw them in here so you don’t have to remember them.</p>
- </td>
- </tr>
- <tr>
- <td>
- <p><code>_includes</code></p>
- </td>
- <td>
- <p>These are the partials that can be mixed and matched by your _layouts and _posts to facilitate reuse. The liquid tag <code>{{ "{% include file.ext " }}%}</code> can be used to include the partial in <code>_includes/file.ext</code>.</p>
- </td>
- </tr>
- <tr>
- <td>
- <p><code>_layouts</code></p>
- </td>
- <td>
- <p>These are the templates which posts are inserted into. Layouts are chosen on a post-by-post basis in the <a href="../frontmatter">YAML front matter</a>, which is described in the next section. The liquid tag <code>{{ "{{ content " }}}}</code> is used to inject data onto the page.</p>
- </td>
- </tr>
- <tr>
- <td>
- <p><code>_posts</code></p>
- </td>
- <td>
- <p>Your dynamic content, so to speak. The format of these files is important, as named as <code>YEAR-MONTH-DAY-title.MARKUP</code>. The <a href="../permalinks">permalinks</a> can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name.</p>
- </td>
- </tr>
- <tr>
- <td>
- <p><code>_site</code></p>
- </td>
- <td>
- <p>This is where the generated site will be placed once Jekyll is done transforming it. It's probably a good idea to add this to your <code>.gitignore</code> file.</p>
- </td>
- </tr>
- <tr>
- <td>
- <p><code>index.html</code> and other HTML, Markdown, Textile files</p>
- </td>
- <td>
- <p>Provided that the file has a <a href="../frontmatter">YAML Front Matter</a> section, it will be transformed by Jekyll. The same will happen for any <code>.html</code>, <code>.markdown</code>, <code>.md</code>, or <code>.textile</code> file in your site's root directory or directories not listed above.</p>
- </td>
- </tr>
- <tr>
- <td>
- <p>Other Files/Folders</p>
- </td>
- <td>
- <p>Every other directory and file except for those listed above—such as <code>css</code> and <code>images</code> folders, <code>favicon.ico</code> files, and so forth—will be transferred over verbatim to the generated site. There's plenty of <a href="../sites">sites already using Jekyll</a> if you're curious as to how they're laid out.</p>
- </td>
- </tr>
- </tbody>
-</table>
View
37 site/_posts/2012-07-01-structure.textile
@@ -0,0 +1,37 @@
+---
+layout: docs
+title: Directory structure
+prev_section: usage
+next_section: configuration
+---
+
+Jekyll at its core is a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed on the layout and more. This is all done through strictly editing files, and the web interface is the final product.
+
+A basic Jekyll site usually looks something like this:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes
+| ├── footer.html
+| └── header.html
+├── _layouts
+| ├── default.html
+| └── post.html
+├── _posts
+| ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
+| └── 2009-04-26-barcamp-boston-4-roundup.textile
+├── _site
+└── index.html
+{% endhighlight %}
+
+An overview of what each of these does:
+
+(thead). |_. File / Directory |_. Description |
+| @_config.yml@ | Stores "configuration":../configuration data. A majority of these options can be specified from the command line executable but it’s easier to throw them in here so you don’t have to remember them. |
+| @_includes@ | These are the partials that can be mixed and matched by your @_layouts@ and @_posts@ to facilitate reuse. The liquid tag @{{ "{% include file.ext " }}%}@ can be used to include the partial in @_includes/file.ext@. |
+| @_layouts@ | These are the templates which posts are inserted into. Layouts are chosen on a post-by-post basis in the "YAML front matter":../frontmatter, which is described in the next section. The liquid tag @{{ "{{ content " }}}}@ is used to inject data onto the page. |
+| @_posts@ | Your dynamic content, so to speak. The format of these files is important, as named as @YEAR-MONTH-DAY-title.MARKUP@. The "permalinks":../permalinks can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name. |
+| @_site@ | This is where the generated site will be placed once Jekyll is done transforming it. It's probably a good idea to add this to your @.gitignore@ file. |
+| @index.html@ and other HTML, Markdown, Textile files | Provided that the file has a "YAML Front Matter":../frontmatter section, it will be transformed by Jekyll. The same will happen for any <code>.html</code>, <code>.markdown</code>, <code>.md</code>, or <code>.textile</code> file in your site's root directory or directories not listed above. |
+| Other Files/Folders | Every other directory and file except for those listed above—such as <code>css</code> and <code>images</code> folders, <code>favicon.ico</code> files, and so forth—will be transferred over verbatim to the generated site. There's plenty of "sites already using Jekyll":../sites if you're curious as to how they're laid out. |
View
32 site/css/style.css
@@ -281,7 +281,7 @@ body > footer .align-right img {
border-radius: 10px;
padding: 40px 40px 30px;
box-shadow: 0 3px 10px rgba(0,0,0,.1);
- min-height: 800px;
+ min-height: 860px;
}
.docs aside {
@@ -406,7 +406,7 @@ pre, code {
line-height: 1.8em;
}
-.highlight, p > pre, p > code {
+.highlight, p > pre, p > code, td > code {
background: #333;
color: #fff;
border-radius: 5px;
@@ -505,7 +505,7 @@ table {
box-shadow: 0 1px 3px rgba(0,0,0,.3);
}
-thead {
+.thead {
border-top-left-radius: 5px;
border-top-right-radius: 5px;
color: #fff;
@@ -520,27 +520,19 @@ thead {
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#3a3a3a', endColorstr='#1e1e1e',GradientType=0 );
}
-thead th {
+.thead th {
position: relative;
box-shadow: inset 0 1px 0 rgba(255,255,255,.1);
}
-thead th:first-child {
+.thead th:first-child {
border-top-left-radius: 5px;
}
-thead th:last-child {
+.thead th:last-child {
border-top-right-radius: 5px;
}
-td {
- padding: .5em .75em;
-}
-
-td p {
- margin: 0;
-}
-
th {
text-transform: uppercase;
font-size: 16px;
@@ -549,7 +541,11 @@ th {
color: #888;
}
-tbody td {
+td {
+ font-size: 16px;
+ line-height: 1.5em;
+ padding: .5em .75em;
+ margin: 0;
border-top: 1px solid rgba(0,0,0,.1);
box-shadow: inset 0 1px 0 rgba(255,255,255,.1);
background: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiA/Pgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCUiIGhlaWdodD0iMTAwJSIgdmlld0JveD0iMCAwIDEgMSIgcHJlc2VydmVBc3BlY3RSYXRpbz0ibm9uZSI+CiAgPGxpbmVhckdyYWRpZW50IGlkPSJncmFkLXVjZ2ctZ2VuZXJhdGVkIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjAlIiB5MT0iMCUiIHgyPSIwJSIgeTI9IjEwMCUiPgogICAgPHN0b3Agb2Zmc2V0PSIwJSIgc3RvcC1jb2xvcj0iI2ZmZmZmZiIgc3RvcC1vcGFjaXR5PSIwLjEiLz4KICAgIDxzdG9wIG9mZnNldD0iMTAwJSIgc3RvcC1jb2xvcj0iI2ZmZmZmZiIgc3RvcC1vcGFjaXR5PSIwIi8+CiAgPC9saW5lYXJHcmFkaWVudD4KICA8cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMSIgaGVpZ2h0PSIxIiBmaWxsPSJ1cmwoI2dyYWQtdWNnZy1nZW5lcmF0ZWQpIiAvPgo8L3N2Zz4=);
@@ -562,11 +558,7 @@ tbody td {
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#1affffff', endColorstr='#00ffffff',GradientType=0 );
}
-td p {
- font-size: 16px;
-}
-
-td p code {
+td code {
font-size: 14px;
}
Something went wrong with that request. Please try again.