From c3c71f186e2ab50a7f465fd1a10f0b8f938d09c3 Mon Sep 17 00:00:00 2001 From: Shan Carter Date: Thu, 5 Jan 2017 13:24:50 -0800 Subject: [PATCH] More docs --- examples/tutorial.html | 100 ++++++++++++++++++++++++++--------------- 1 file changed, 64 insertions(+), 36 deletions(-) diff --git a/examples/tutorial.html b/examples/tutorial.html index 99b3710..b96dffd 100644 --- a/examples/tutorial.html +++ b/examples/tutorial.html @@ -21,9 +21,9 @@

How to Create a Distill Article

A collection of examples and best practices for creating interactive explanatory articles using the Distill web framework

-

Distill ships with a CSS framework and a collection of custom web components that make building interactive academic articles easier than raw HTML, CSS and JavaScript. This reference article details several examples and best practices for how to use both frameworks. Both are also available on Github with a permissive license, so feel free to use them independent of http://distill.pub as well.

+

Distill ships with a CSS framework and a collection of custom web components that make building interactive academic articles easier than with raw HTML, CSS and JavaScript. This reference article details several examples and best practices for how to use both frameworks.

-

Setting up a Document

+

Getting Started

If you’re using Chrome as your development browser, here is the smallest distill post.

<script src="../dist/template.min.js"></script> @@ -31,7 +31,7 @@ <h1>Hello World</h1> </dt-article> -

However, this omits some required html tags that might cause rendering problems during development if you’re using a browser other than Chrome. These missing tags will be added during publishing, so if the above works for you, feel free to use it. If you are having issues with weird characters showing up, try adding doctype and meta tags explicitly.

+

However, this omits some required html tags that might cause rendering problems during development if you’re using a browser other than Chrome. These missing tags will be added during publishing, so if the above works for you, feel free to use it. If you are having issues, try adding doctype and meta tags explicitly.

<!doctype html> <meta charset="utf-8"> @@ -45,12 +45,27 @@ <!doctype html> <meta charset="utf-8"> <script src="../dist/template.min.js"></script> + <dt-front-matter> + { + title: "Article Title", + description: "Description of the post" + } + </dt-front-matter> <dt-article> <h1>Hello World</h1> - <h2>A description of the post</h2> + <h2>A description of the article</h2> <dt-byline></dt-byline> + <p>This is the first paragraph of the article.</p> + <p>We can also cite <dt-cite>@gregor2015draw</dt-cite> external publications.</p> </dt-article> - <dt-bibliography></dt-bibliography> + <dt-bibliography> + @article{gregor2015draw, + title={DRAW: A recurrent neural network for image generation}, + author={Gregor, Karol and Danihelka, Ivo and Graves, Alex and Rezende, Danilo Jimenez and Wierstra, Daan}, + journal={arXivreprint arXiv:1502.04623}, + year={2015} + } + </dt-bibliography>

Markdown

@@ -60,7 +75,7 @@ <meta charset="utf-8"> <script src="../dist/template.min.js"></script> <dt-article markdown> - ###Hello World + #Hello World ##A description of the post @@ -68,38 +83,25 @@ </dt-article> <dt-bibliography></dt-bibliography> -

We use marked as the rendering engine, with github flavored markdown and smartypants enabled. In development mode the markdown is translated in the client after the dom content has loaded, but when published the translation is precompiled.

+

We use marked as the rendering engine, with github flavored markdown and smartypants enabled. In development mode the markdown is translated in the client after the dom content has loaded, but when published, the translation is precompiled.

-

Data

-
-

Layouts

-

The main text column is referred to as the body. It is the assumed layout of any direct descendents of the dt-article element.

-

.l-body

-

.l-middle

-

.l-page

-

Occasionally you’ll want to use the full browser width. For this, use screen. You can also inset the element a little from the edge of the browser by appending, you guessed it, inset.

-

.l-screen

-

.l-screen-inset

-

Often you want to position smaller images so as not to completely interrupt the flow of your text. Or perhaps you want to put some text in the margin as an aside or to signal that it’s optional content. For these cases we’ll use the float-based .side layouts.

-

.l-body.side

-

.l-page.side

-

They are all floated to the right and anchored to the right-hand edge of the position you specify. By default, each will take up approximately half of the width of the standard layout position, but you can override the width with a more specific selector.

-

.l-gutter

-

The final layout is for marginalia, asides, and footnotes. It does not interrupt the normal flow of .l-body sized text except on mobile screen sizes.

- -
-

Code Blocks

-

Syntax highlighting is provided within <dt-code> tags. An example of inline code snippets: <dt-code language="html">let x = 10;</dt-code>. For larger blocks of code, add a block attribute:

+

Front Matter

+

You’ll need to describe some data about you post — title, description, authors, etc. For this use the <dt-front-matter> tag.

- <dt-code block language="javascript"> - var x = 25; - function(x){ - return x * x; + <dt-front-matter> + { + title: "Article Title", + description: "Description of the post", + authors: [] } - </dt-code> + </dt-front-matter> + +

You can also use an external JSON file if you like. We will automatically make a request for a ./distill.json file if there is no <dt-front-matter> element on the page, or you can point to another file with the src attribute. In production, these files will be inlined into the document.

+ + <dt-front-matter src="./distill.json"></dt-front-matter>
-

Citation

+

Citations

Bibtex is the supported way of making academic citations. You first need have a global definition of all your possible citations. This can either be inlined in the document, or it can reference an external bibtex file.

<dt-bibliography> @@ -128,15 +130,41 @@

Take a look at this paper gregor2015draw.

-

Math

+

Code Blocks

+

Syntax highlighting is provided within <dt-code> tags. An example of inline code snippets: <dt-code language="html">let x = 10;</dt-code>. For larger blocks of code, add a block attribute:

+ + <dt-code block language="javascript"> + var x = 25; + function(x){ + return x * x; + } + </dt-code> + +

Footnotes

This is a

-

HTML Includes

+

Math

-

Authors

+

Layouts

+

The main text column is referred to as the body. It is the assumed layout of any direct descendents of the dt-article element.

+

.l-body

+

.l-middle

+

.l-page

+

Occasionally you’ll want to use the full browser width. For this, use screen. You can also inset the element a little from the edge of the browser by appending, you guessed it, inset.

+

.l-screen

+

.l-screen-inset

+

Often you want to position smaller images so as not to completely interrupt the flow of your text. Or perhaps you want to put some text in the margin as an aside or to signal that it’s optional content. For these cases we’ll use the float-based .side layouts.

+

.l-body.side

+

.l-page.side

+

They are all floated to the right and anchored to the right-hand edge of the position you specify. By default, each will take up approximately half of the width of the standard layout position, but you can override the width with a more specific selector.

+

.l-gutter

+

The final layout is for marginalia, asides, and footnotes. It does not interrupt the normal flow of .l-body sized text except on mobile screen sizes.

+ +
+

Including External Files