3 #+seq_todo: TODO DRAFT DONE
4 #+startup: indent showall
10 ** Computers are the Devil
12 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/blog.png
13 :EXPORT_FILE_NAME: _index
14 :EXPORT_HUGO_MENU: :menu "main" :weight -1 :title Blog
17 ** DONE Using ox-hugo To Build Websites with Emacs :org:emacs:hugo:@tutorial:
18 CLOSED: [2018-04-11 Wed 21:56]
20 :EXPORT_FILE_NAME: ox-hugo-tutorial
21 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
22 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
24 This article explains in detail the process of setting up a bare-bones website
25 using Hugo and org-mode. My goal in writing this is to provide readers with a
26 superior understanding of the fundamentals of this workflow. It is by no means
27 an exhaustive explanation of org-mode or Emacs, but should give readers of any
28 skill level a strong foundation to apply their own knowledge and techniques to
29 the Emacs-Hugo toolchain.
31 I assume only beginner-level knowledge of Emacs.
34 [[https://github.com/kaushalmodi][Kaushal Modi]] made ox-hugo by extending org's ox-blackfriday package, providing
35 an impressive amount of features for organizing blog text and linked data with
36 Hugo. He maintains [[https://ox-hugo.scripter.co/][great documentation]] and ample [[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content-org][examples]] for using the
37 package. I will explain my own workflow here, but for an exhaustive (though
38 terse) reference, I highly recommend Modi's [[https://ox-hugo.scripter.co/test/][test site]] and [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org][post source]] org file,
39 which contain demonstrations and tests for all of ox-hugo's features.
41 After issuing the Emacs command ~M-x package-install RET ox-hugo RET~, you'll
42 need to ~require~ it. You can do this by running ~M-: (require 'ox-hugo)~, but
43 you'll want to add it to your configuration as explained [[https://ox-hugo.scripter.co/doc/usage/][here]]. Once this is
44 done, using ox-hugo is just a matter of making an org file and writing
45 content. Org's format is very straightforward, and is designed to make sense to
46 the reader even if they're unfamiliar with the formal syntax. For instance,
49 | Where's My Food? | Fridge | Counter | Mouth | Total |
50 | Oranges | 1 | 3 | 0 | :=vsum($2..$4) |
51 | Marshmallows | 0 | 100 | 20 | :=vsum($2..$4) |
52 | Brussel Sprouts | 32 | 4 | 0 | :=vsum($2..$4) |
54 Produces a dynamic spreadsheet table in org-mode that exports to HTML like this:
56 | Where's My Food? | Fridge | Counter | Mouth | Total |
57 | Oranges | 1 | 3 | 0 | 4 |
58 | Marshmallows | 0 | 100 | 20 | 120 |
59 | Brussel Sprouts | 32 | 4 | 0 | 36 |
60 #+TBLFM: @2$5=vsum($2..$4)::@3$5=vsum($2..$4)::@4$5=vsum($2..$4)
62 If you're already familiar with org-mode, the benefits are obvious and creating
63 content is fairly trivial. Org-mode is, however, a complex and expansive program
64 with many features, and its learning curve can appear daunting at first glance.
65 Using ox-hugo is a great way to learn the format, since it gives the author a
66 command-center view of their entire content hierarchy, much like a traditional
67 database, but in a flat format that's much easier to read and understand. Org
68 features present themselves naturally, and the author can easily visualize the
69 correspondence between the org format and the output on their webpage.
71 Just take a look at the [[https://www.kengrimes.com/gitweb/?p=kengrimes.com/content.git;a=blob_plain;f=content.org;hb=HEAD][org file]] for this webpage. Search for "ox-hugo is super
72 cool!" and you should find this very paragraph.
74 Eventually you'll want to [[https://orgmode.org/manual/][read the manual]], though. You may access it in Emacs
78 Compared to a generic org file, the only important "extra" data that ox-hugo
79 needs to properly export data is a ~:PROPERTIES: ... :END:~ block with
80 definitions used for Hugo's [[https://gohugo.io/content-management/front-matter/][front matter]] (used for associating a title, header,
81 or other custom data with the page it generates). ~:PROPERTIES:~ blocks are
82 common in org for defining arbitrary metadata about sections, and can be used in
83 many such ways. Providing an ~:EXPORT_FILE_NAME:~ definition signals to ox-hugo
84 that this heading is available for export, and that it should be exported to a
85 markdown file with the name provided. For example, the ~:PROPERTIES:~ block of
86 the page you're currently reading looks like this:
89 :EXPORT_FILE_NAME: ox-hugo
90 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
91 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
94 The ~:caption~ and ~:header~ variables are optional definitions allowed by the
95 Speedy theme of this website, but the filename is the only required property for
96 ox-hugo. So, as a minimal example, here's what a new blog might look like in its
102 :EXPORT_HUGO_SECTION:
103 :EXPORT_FILE_NAME: _index
105 This is the home of my blog!
108 :EXPORT_FILE_NAME: herpes
110 Someone gave me herpes! Oh no!
112 The org file can be placed in any directory so long as ~HUGO_BASE_DIR~ correctly
113 identifies the Hugo project's root directory. This path definition is required
114 for any valid ox-hugo file, and in the example above uses ~.~ as the base
115 directory, which assumes that the file will be placed in the hugo project's base
116 directory. If you saved this file as hugotest.org, exported it with org's
117 exporter ~C-c C-e~ and selected the Hugo output ~H~ and the All Subtrees To
118 Files option ~A~, you'd wind up with the following files in your directory:
126 Most sites will be more than a blog, though, and will want multiple sections. In
127 fact, many sites are made up of nothing but a slew of sections that users
128 navigate between with some built-in menu. So a more functional minimal example
129 would be the following:
134 :EXPORT_HUGO_SECTION:
135 :EXPORT_FILE_NAME: _index
136 :EXPORT_HUGO_MENU: :menu "main"
138 This is the home of my blog!
141 :EXPORT_HUGO_SECTION: posts
145 :EXPORT_HUGO_MENU: :menu "main"
146 :EXPORT_FILE_NAME: _index
148 Man, look at all my blog posts.
151 :EXPORT_FILE_NAME: herpes
153 Someone gave me herpes! Oh no!
155 Which yields the following:
165 As you might expect, this structure adheres to the Hugo [[https://gohugo.io/content-management/organization/][content management]]
166 scheme. Additionally, the index files have been marked with menu metadata, which
167 allows Hugo themes to automatically generate navigation menus from the markdown
168 files. Hereafter, making new blog posts is as simple as adding new sub-headings
169 under the "My Blog" heading, and exporting. As you can see, this is suitable for
170 defining the hierarchical structure of any general website, not just
171 blogs. Org-mode and Hugo just make creating new pages so simple and
172 well-structured that providing content is all that's required for a new page,
173 blog entry, or entirely new site section. If you can blog with ox-hugo, you can
174 deftly deploy any manner of web content, or even develop entire websites as
175 naturally as you make blog posts. Any tool that can turn blogging and web
176 development into the same task is quite an achievement!
178 Of course, themes to style this content are another can of worms entirely, but
179 it is sufficient for now to mention that Hugo makes [[https://gohugo.io/themes/installing-and-using-themes/][using themes]] as easy as
180 downloading one and specifying it in Hugo's config file.
182 One question you may ask is why the blog's homepage is not defined in the *My
183 Blog* heading. This is a fair question! Property blocks are inherited by
184 sub-headings, and as of the current version of ox-hugo even ~:EXPORT_HUGO_MENU:~
185 properties are inherited. This might be intended by the content creator, but
186 most likely you don't want every single post you make to be in the main menu. So
187 it makes sense to define all your pages, including the index, as a sub-heading
188 of the section definition (which specifies which sub-directory content will
191 To illustrate, let's assume you want to extend the previous site definition with
192 a section about fishsticks.
193 #+begin_src org -n 24
196 :EXPORT_HUGO_MENU: :menu "main"
197 :EXPORT_HUGO_SECTION: fishsticks
198 :EXPORT_FILE_NAME: _index
200 This section devoted to Orson Wells, R.I.P.
203 :EXPORT_FILE_NAME: van-de-camps
205 If this is fish, I'll be a monkey's uncle.
208 :EXPORT_FILE_NAME: gortons
210 I think these gave me the herpes.
212 In this example, we've defined the main homepage of the section inside the
213 tier-1 heading for Fishsticks. This is valid, and produces the expected file output:
220 │ │ └── van-de-camps.md
227 But on inspection of the gortons.md file, we find the anomoly mentioned above:
228 #+begin_src markdown -n
231 author: ["Ken Grimes"]
236 identifier: "gortons"
239 I think these gave me the herpes.
241 Uh oh! Not only did these fishsticks give us herpes, they are now part of the
242 main menu. Tisk tisk. So if you use this workflow, be sure to put your index
243 pages in subheadings so that the tier-1 heading can be used for "global"
244 definitions that affect all of the pages.
246 Another question might be why the index pages are named *_index*. You can use
247 *index* instead of *_index*, the only difference is whether Hugo treats the
248 index page as a leaf, or a branch, when [[https://gohugo.io/content-management/page-bundles/][bundling resources]] for Hugo to query
249 during site generation. This is a relatively new addition to Hugo as of version
250 0.39, and isn't fully functional or integrated well into ox-hugo, so I simply
251 don't use it at the moment. I define all indexes as *_index* to make them
252 branches because, in future versions, packaging files within bundles like this
253 will provide a more stable way for Hugo themes to reference page- and
254 section-specific files that accompany the content. Currently, I store all such
255 files in the static folder, which is copied verbatim to the output directory by
256 Hugo when the site is built.
259 At this point, setting up Hugo and publishing is simple. [[https://gohugo.io/getting-started/installing/][Installing]] Hugo is
260 pretty straightforward on any Unix-like system with a package manager; it is
261 available on most distributions at this point. Windows installation is a bigger
262 pain in the ass, but you should be used to that if you're still in the
265 Using ~hugo new site .~ on the command-line will create a new hugo site in the
266 current directory, but ~hugo~ expects to be creating a new directory with this
267 command and will complain if it already exists. It also provides the ~--force~
268 option to allow creating a new site in an extant directory, but this too will
269 fail if the *content* subdirectory already exists (which ox-hugo will create
272 So you have three choices:
273 1. run ~hugo new site /path/to/some-new-dir~ and move your org file to it
274 2. simply ~rm -Rf content/~ to remove the content directory ox-hugo created,
275 then run ~hugo new site --force .~
276 3. don't even bother with the ~hugo new site~ command, and make a *config.toml*
279 It's convenient to do this through the ~hugo~ command because it will create
280 Hugo-specific subdirectories like archetypes, layouts, themes, etcetera, in
281 addition to populating a basic *config.toml* file. The subdirectories it creates
282 aren't necessary, but help illustrate Hugo's structure. In any case, you'll want
283 to wind up with a directory structure something like this (created with option 2
284 above, extending from previous examples):
297 Exporting with ox-hugo using ~C-c C-e H A~ again will, as expected, fill the
298 content directory with our content.
308 │ │ └── van-de-camps.md
319 Now, running the command ~hugo~ with no subcommands will invoke the Hugo
320 generator on the current directory, and output finalized content in the
331 │ │ └── van-de-camps.md
353 Hugo, by default, generates xml files that are suitable for RSS feeds. With a
354 theme installed, Hugo will produce more suitable web content (usually
355 HTML). You'll notice from this default output however that Hugo creates a
356 sitemap, and two directories for [[https://gohugo.io/content-management/taxonomies/][taxonomies]] that let you "tag" and "categorize"
357 content. The taxonomy index pages allow users to browse content by category or
358 tag. These taxonomies correspond to org-mode tags, and ox-hugo will
359 automatically associated tagged headings with the tags taxonomy, or the
360 categories taxonomy if prefixed with an @ symbol. You are free to define your
361 own taxonomies, and even disable the default "tags" and "categories" taxonomies,
362 but since org-mode tags directly translate to the default Hugo taxonomies, it
363 makes sense to just use the default taxonomies for now.
365 *** Example Hugo Site
366 As an example, let's add some tags and categories to our *hugotest.org* file:
371 :EXPORT_HUGO_SECTION:
372 :EXPORT_FILE_NAME: _index
373 :EXPORT_HUGO_MENU: :menu "main"
375 This is the home of my blog!
378 :EXPORT_HUGO_SECTION: posts
382 :EXPORT_HUGO_MENU: :menu "main"
383 :EXPORT_FILE_NAME: _index
385 Man, look at all my blog posts.
386 ,** I have herpes :@inanity:herpes:fear:
388 :EXPORT_FILE_NAME: herpes
390 Someone gave me herpes! Oh no!
393 :EXPORT_HUGO_MENU: :menu "main"
394 :EXPORT_HUGO_SECTION: fishsticks
395 :EXPORT_FILE_NAME: _index
397 This section devoted to Orson Wells, R.I.P.
398 ,** Van De Camps :@inanity:
400 :EXPORT_FILE_NAME: van-de-camps
402 If this is fish, I'll be a monkey's uncle.
403 ,** Gortons :@inanity:herpes:
405 :EXPORT_FILE_NAME: gortons
407 I think these gave me the herpes.
409 Exporting *hugotest.org* with ~C-c C-e H A~ and generate with ~hugo~ will yield
410 the same file structure as before, but this time we'll see that the categories
411 and tags directories have sections for our newly added tags.
421 │ │ └── van-de-camps.md
447 The index pages of taxonomies provide a list of all available taxonomies of that
448 type, with links to lists that show content associated with that taxonomy. For
449 instance, public/tags/index.xml looks like this:
451 <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
452 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
454 <title>Tags on My New Hugo Site</title>
455 <link>http://example.org/tags/</link>
456 <description>Recent content in Tags on My New Hugo Site</description>
457 <generator>Hugo -- gohugo.io</generator>
458 <language>en-us</language>
460 <atom:link href="http://example.org/tags/index.xml" rel="self" type="application/rss+xml" />
465 <link>http://example.org/tags/fear/</link>
466 <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
468 <guid>http://example.org/tags/fear/</guid>
469 <description></description>
473 <title>Herpes</title>
474 <link>http://example.org/tags/herpes/</link>
475 <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
477 <guid>http://example.org/tags/herpes/</guid>
478 <description></description>
484 And public/tags/fear/index.xml looks like this:
486 <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
487 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
489 <title>Fear on My New Hugo Site</title>
490 <link>http://example.org/tags/fear/</link>
491 <description>Recent content in Fear on My New Hugo Site</description>
492 <generator>Hugo -- gohugo.io</generator>
493 <language>en-us</language>
495 <atom:link href="http://example.org/tags/fear/index.xml" rel="self" type="application/rss+xml" />
499 <title>I have herpes</title>
500 <link>http://example.org/posts/herpes/</link>
501 <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
503 <guid>http://example.org/posts/herpes/</guid>
504 <description>Someone gave me herpes! Oh no!</description>
508 <title>Van De Camps</title>
509 <link>http://example.org/fishsticks/van-de-camps/</link>
510 <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
512 <guid>http://example.org/fishsticks/van-de-camps/</guid>
513 <description>If this is fish, I&rsquo;ll be a monkey&rsquo;s uncle.</description>
519 This allows themes to easily build navigation pages for browsing or querying
520 taxonomies. Files like these are often useful to output as JSON (done by the
521 theme) to allow Javascript-driven dynamic search features, but a simpler scheme
522 can output HTML pages to browse taxonomies just as you would posts in a section
523 (i.e. org-mode heading).
526 The last thing to do here is to download or create a theme for Hugo. As
527 mentioned before, installing a theme is very simple. This blog uses a custom
528 theme named Speedy that I have been developing to help myself learn Hugo's
529 internals, but for this example I'll be using Kaushal Modi's [[https://github.com/kaushalmodi/hugo-bare-min-theme][bare-min theme]]. The
530 bare-min theme is the best starting place out there for making new themes, and
531 outputs basic HTML pages without any need to mess with CSS or JS. It also
532 provides easy debugging facilities and search features.
534 We'll just install it and generate the site again. You can download the theme
535 from its github page and extract it to the themes folder, or much more easily
536 use git to clone it to your themes directory.
537 ~git clone https://github.com/kaushalmodi/hugo-bare-min-theme.git themes/bare-min~
538 Then open up your *config.toml* file, and add the theme.
540 baseURL = "http://example.org/"
541 languageCode = "en-us"
542 title = "My New Hugo Site"
546 Be sure that the theme's name matches the theme directory's name in the themes/
547 directory of your project base directory. (e.g. themes/bare-min here).
549 That's it for installing the theme. Just run ~hugo~ again, and behold your output:
560 │ └── github_chroma.css
591 The bare-min theme outputs HTML, provides CSS for doing chroma-based syntax
592 highlighting (in case you include code blocks), and inline styles for basic
593 page formatting. Generated pages also have a lot of useful debugging information.
595 You can now serve the *public/* directory over an HTTP server. Hugo is packaged
596 with an internal [[https://gohugo.io/commands/hugo_server/][HTTP server]] to help with testing, which is quite convenient
597 because it can automatically refresh whenever content in its content directory
598 is updated (so when you export from ox-hugo, you don't have to run ~hugo~
599 again). To use it, simply run ~hugo server~ and point your browser at
600 http://localhost:1313 (1313 is the default ~--port~ argument for ~hugo server~).
602 Eventually you'll want to move on to other themes, or develop your own, but at
603 this point you've got a fully functional blog publishing workflow from start to
606 *** Attaching Files, Capturing Information & Automation
607 Once you have a basic site structured in your org file, you're ready to start
608 throwing information in it. It is of course sufficient to open the org file and
609 edit it, but most org-mode users prefer to automate /everything/, and being able
610 to use org's capture feature to instantly populate new blog posts is extremely
613 The [[https://ox-hugo.scripter.co/][ox-hugo documentation]] provides succinct explanations on how to do this,
614 including elisp snippets for [[https://ox-hugo.scripter.co/doc/org-capture-setup/][capture setup]], [[https://ox-hugo.scripter.co/doc/images-in-content/][image linking]], and [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][automating
615 exports]] when you save your org file (so no more need to ~C-c C-e H A~ every
616 time, just save the file as usual with ~C-x C-s~).
617 ** DONE I did a blog :blog:org:emacs:hugo:
618 CLOSED: [2018-04-06 Fri 18:29]
620 :EXPORT_FILE_NAME: ox-hugo
621 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
622 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
624 ox-hugo is an [[http://en.wikipedia.org/wiki/Emacs][Emacs]] package for [[http://en.wikipedia.org/wiki/org-mode][org-mode]] that produces input for the static
625 content generator [[https://gohugo.io/][Hugo]], which I use for this website. Today I integrated its
626 expectations about file structure into the Speedy theme for this blog, allowing
627 me to keep all blog contents in a single org-mode file and export [[http://en.wikipedia.org/wiki/markdown][markdown]]
628 content for Hugo's excellent [[https://github.com/russross/blackfriday][blackfriday markdown parser]] (a markdown format with
629 many added features). Hugo does support limited parsing of org files internally,
630 but org-mode features like inline spreadsheets and system communication are
631 beyond the scope of most external tools, so org-mode is best used as an
632 exporter. As an Emacs user, this allows me to instantly capture interesting
633 information I come across and publish it within seconds. Now I have no excuses!
635 ** DONE Another topic
636 CLOSED: [2018-04-01 Sun 18:29]
638 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
639 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
640 :EXPORT_FILE_NAME: another-topic-1
642 This is just another topic, don't worry about it.
644 ** DONE Another topic :@test:test:
645 CLOSED: [2018-04-01 Sun 18:30]
647 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
648 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
649 :EXPORT_FILE_NAME: another-topic-2
651 This is just another topic, don't worry about it.
653 ** DONE Another topic :@test:test:
654 CLOSED: [2018-04-01 Sun 18:30]
656 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
657 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
658 :EXPORT_FILE_NAME: another-topic-3
660 This is just another topic, don't worry about it.
662 ** DONE Another topic :@test:test:
663 CLOSED: [2018-04-01 Sun 18:30]
665 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
666 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
667 :EXPORT_FILE_NAME: another-topic-4
669 This is just another topic, don't worry about it.
670 ** DONE Another topic :@test:test:
671 CLOSED: [2018-04-01 Sun 18:30]
673 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
674 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
675 :EXPORT_FILE_NAME: another-topic-5
677 This is just another topic, don't worry about it.
678 ** DONE Another topic :@test:test:
679 CLOSED: [2018-04-01 Sun 18:30]
681 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
682 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
683 :EXPORT_FILE_NAME: another-topic-6
685 This is just another topic, don't worry about it.
686 ** DONE Another topic :@test:test:
687 CLOSED: [2018-04-01 Sun 18:30]
689 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
690 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
691 :EXPORT_FILE_NAME: another-topic-7
693 This is just another topic, don't worry about it.
694 ** DONE Another topic :@test:test:
695 CLOSED: [2018-04-01 Sun 18:30]
697 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
698 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
699 :EXPORT_FILE_NAME: another-topic-8
701 This is just another topic, don't worry about it.
702 ** DONE Another topic :@test:test:
703 CLOSED: [2018-04-01 Sun 18:30]
705 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
706 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
707 :EXPORT_FILE_NAME: another-topic-9
709 This is just another topic, don't worry about it.
710 ** DONE Another topic :@test:test:
711 CLOSED: [2018-04-01 Sun 18:30]
713 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
714 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
715 :EXPORT_FILE_NAME: another-topic-10
717 This is just another topic, don't worry about it.
718 ** DONE Another topic :@test:test:
719 CLOSED: [2018-04-01 Sun 18:30]
721 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
722 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
723 :EXPORT_FILE_NAME: another-topic-11
725 This is just another topic, don't worry about it.
726 ** DONE Another topic :@test:test:
727 CLOSED: [2018-04-01 Sun 18:30]
729 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
730 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
731 :EXPORT_FILE_NAME: another-topic-12
733 This is just another topic, don't worry about it.
734 ** DONE Another topic :@test:test:
735 CLOSED: [2018-04-01 Sun 18:30]
737 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
738 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
739 :EXPORT_FILE_NAME: another-topic-13
741 This is just another topic, don't worry about it.
744 :EXPORT_FILE_NAME: _index
745 :EXPORT_HUGO_MENU: :menu "main"
746 :EXPORT_HUGO_SECTION: forth
747 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading "Highly Factored Code"
748 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/forth.png
750 This is where I post my watForth programs.
752 At present, my forth testbed is located at https://forth.kengrimes.com
756 :EXPORT_FILE_NAME: _index
757 :EXPORT_HUGO_MENU: :menu "main" :title Git
758 :EXPORT_HUGO_SECTION: git
759 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/git.png
761 <iframe height="600px" width="100%" frameborder="0" scrolling="no" src="/gitweb" onload="resizeIFrame(this)">
762 <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
763 <a href="https://git.kengrimes.com">https://git.kengrimes.com</a>
768 :EXPORT_HUGO_SECTION: about
769 :EXPORT_HUGO_MENU: :menu "main" :title About
770 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading '("Ken Grimes" "Computer Scientist" "At Large")
771 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/home.png
772 :EXPORT_FILE_NAME: _index
774 Hi! I'm Ken, a 34-year-old computer scientist currently living in Irvine,
775 California. This is a website I've constructed for the purpose of developing
776 web-facing software. I will probably blog with it once development is
777 complete. In the mean time, if you're curious, this is my [[file:static/cv.pdf][curriculum vitae]]
781 #+attr_html: :class center
782 [[file:static/img/emacs-logo.png]]
784 Org-mode is sometimes seen as an esoteric tool for an already esoteric IDE
785 (Emacs), but to me it is the natural evolution of decades of careful work to do
786 things the right way. When a software developer, after much study and
787 deliberation, finally comes to the realization that we are all fundamentally
788 programming one enormous system, it suddenly becomes important to understand the
789 fundamentals of computing and peel away the abstractions we live in like layers
790 of an onion. At the core, computer scientists will find that Names and Naming
791 are the universal "API" with which we all work. As such, being able to work with
792 raw words is invaluable to any serious student of computing. This is why the
793 much ignored medium of plain text is, somewhat paradoxically, the most powerful
794 of all tools for us. Indeed, Names and Naming have a long history of association
795 with power, and it seems most sciences that recognize this relationship are
796 themselves deemed "esoteric".
798 It's easy to get washed away in the torrent of new-age development tools that
799 add layer after layer of abstraction and "boilerplate" automation. These days,
800 it's trivial with tools like [[http://en.wikipedia.org/wiki/Webstorm][Webstorm]], [[http://en.wikipedia.org/wiki/Xcode][Xcode]], or [[http://en.wikipedia.org/wiki/Visual_Studio][Visual Studio]] to start
801 producing working code in minutes, regardless of experience or knowledge. It is
802 much harder, and in many environments impossible, to really understand what you
803 are doing. Most new programming languages, freed from developing sophisticated
804 compiler backends by new tools like [[http://en.wikipedia.org/wiki/llvm][llvm]], have instead focused on providing
805 tooling for automatically formatting, linting, bootstrapping, and even building
806 code to make this process even easier. These tools enforce an opinionated
807 workflow that, although good, are generally not portable to other languages or
808 toolchains. Tools like these are medicine for remedying the enormous time sink
809 and productivity loss suffered during configuration and setup. But like many
810 medicines, they can lead to addiction, and dependency on the vendor who provided
811 it. Eventually, being constrained to a single environment will cause essential
812 skills to atrophy, or never develop in the first place, making the victim a
813 slave to both their vendor and the drug.
815 I'm no tea-totaller, though. These tools are part of my regular workflow, and I
816 advocate using them when it is appropriate. The primary goal in developing
817 skills is to unapolagetically empower yourself by /any/ means necessary. It's a
818 balancing act, in the end, whether the drugs are hurting or hindering. Just be
819 conscious of the debilitating effects of what the buzz-slingers call "vendor
820 lock-in" these days. Study the topic, read the documentation, and understand
821 everything that is going to happen when you invoke any command. This applies to
822 tooling as well as library functions and even language statements - even
823 english. Admittedly, that's a steep mountain to climb for most people, and
824 crippling when wading through spaghetti-code, but you'll come to understand that
825 the most powerful words are the ones you /didn't have to say/ in the first
828 Emacs and Org-mode take these philosophies to heart in different, and incomplete
829 ways. Org-mode is a plain text formatting system, not so dissimilar to markdown,
830 bbcode, or even twitter's automatic recognition of hashtags and @s. It's a
831 formatting engine that recognizes certain plain-text patterns as having special
832 meanings, geared eponymously towards organization of data. For instance,
836 Emacs and Org-mode take these philosophies to heart. Partly because Emacs has
837 been around in some form since the early 70s, While I extend this philosophy to
838 my coding style, it's also integral
840 ** Blackfriday Markdown: Syntax
842 <ul id="ProjectSubmenu">
843 <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
844 <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
845 <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
846 <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
847 <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
851 * [Overview](#overview)
852 * [Philosophy](#philosophy)
853 * [Inline HTML](#html)
854 * [Automatic Escaping for Special Characters](#autoescape)
855 * [Block Elements](#block)
856 * [Paragraphs and Line Breaks](#p)
858 * [Blockquotes](#blockquote)
860 * [Code Blocks](#precode)
861 * [Horizontal Rules](#hr)
862 * [Span Elements](#span)
867 * [Miscellaneous](#misc)
868 * [Backslash Escapes](#backslash)
869 * [Automatic Links](#autolink)
872 **Note:** This document is itself written using Markdown; you
873 can [see the source for it by adding '.text' to the URL][src].
875 [src]: https://raw.githubusercontent.com/russross/blackfriday/master/testdata/Markdown%20Documentation%20-%20Syntax.text
879 <h2 id="overview">Overview</h2>
881 <h3 id="philosophy">Philosophy</h3>
883 Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
885 Readability, however, is emphasized above all else. A Markdown-formatted
886 document should be publishable as-is, as plain text, without looking
887 like it's been marked up with tags or formatting instructions. While
888 Markdown's syntax has been influenced by several existing text-to-HTML
889 filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
890 [Grutatext] [5], and [EtText] [6] -- the single biggest source of
891 inspiration for Markdown's syntax is the format of plain text email.
893 [1]: http://docutils.sourceforge.net/mirror/setext.html
894 [2]: http://www.aaronsw.com/2002/atx/
895 [3]: http://textism.com/tools/textile/
896 [4]: http://docutils.sourceforge.net/rst.html
897 [5]: http://www.triptico.com/software/grutatxt.html
898 [6]: http://ettext.taint.org/doc/
900 To this end, Markdown's syntax is comprised entirely of punctuation
901 characters, which punctuation characters have been carefully chosen so
902 as to look like what they mean. E.g., asterisks around a word actually
903 look like \*emphasis\*. Markdown lists look like, well, lists. Even
904 blockquotes look like quoted passages of text, assuming you've ever
909 <h3 id="html">Inline HTML</h3>
911 Markdown's syntax is intended for one purpose: to be used as a
912 format for *writing* for the web.
914 Markdown is not a replacement for HTML, or even close to it. Its
915 syntax is very small, corresponding only to a very small subset of
916 HTML tags. The idea is *not* to create a syntax that makes it easier
917 to insert HTML tags. In my opinion, HTML tags are already easy to
918 insert. The idea for Markdown is to make it easy to read, write, and
919 edit prose. HTML is a *publishing* format; Markdown is a *writing*
920 format. Thus, Markdown's formatting syntax only addresses issues that
921 can be conveyed in plain text.
923 For any markup that is not covered by Markdown's syntax, you simply
924 use HTML itself. There's no need to preface it or delimit it to
925 indicate that you're switching from Markdown to HTML; you just use
928 The only restrictions are that block-level HTML elements -- e.g. `<div>`,
929 `<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
930 content by blank lines, and the start and end tags of the block should
931 not be indented with tabs or spaces. Markdown is smart enough not
932 to add extra (unwanted) `<p>` tags around HTML block-level tags.
934 For example, to add an HTML table to a Markdown article:
936 This is a regular paragraph.
944 This is another regular paragraph.
946 Note that Markdown formatting syntax is not processed within block-level
947 HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
950 Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
951 used anywhere in a Markdown paragraph, list item, or header. If you
952 want, you can even use HTML tags instead of Markdown formatting; e.g. if
953 you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
954 link or image syntax, go right ahead.
956 Unlike block-level HTML tags, Markdown syntax *is* processed within
960 <h3 id="autoescape">Automatic Escaping for Special Characters</h3>
962 In HTML, there are two characters that demand special treatment: `<`
963 and `&`. Left angle brackets are used to start tags; ampersands are
964 used to denote HTML entities. If you want to use them as literal
965 characters, you must escape them as entities, e.g. `<`, and
968 Ampersands in particular are bedeviling for web writers. If you want to
969 write about 'AT&T', you need to write '`AT&T`'. You even need to
970 escape ampersands within URLs. Thus, if you want to link to:
972 http://images.google.com/images?num=30&q=larry+bird
974 you need to encode the URL as:
976 http://images.google.com/images?num=30&q=larry+bird
978 in your anchor tag `href` attribute. Needless to say, this is easy to
979 forget, and is probably the single most common source of HTML validation
980 errors in otherwise well-marked-up web sites.
982 Markdown allows you to use these characters naturally, taking care of
983 all the necessary escaping for you. If you use an ampersand as part of
984 an HTML entity, it remains unchanged; otherwise it will be translated
987 So, if you want to include a copyright symbol in your article, you can write:
991 and Markdown will leave it alone. But if you write:
995 Markdown will translate it to:
999 Similarly, because Markdown supports [inline HTML](#html), if you use
1000 angle brackets as delimiters for HTML tags, Markdown will treat them as
1001 such. But if you write:
1005 Markdown will translate it to:
1009 However, inside Markdown code spans and blocks, angle brackets and
1010 ampersands are *always* encoded automatically. This makes it easy to use
1011 Markdown to write about HTML code. (As opposed to raw HTML, which is a
1012 terrible format for writing about HTML syntax, because every single `<`
1013 and `&` in your example code needs to be escaped.)
1019 <h2 id="block">Block Elements</h2>
1022 <h3 id="p">Paragraphs and Line Breaks</h3>
1024 A paragraph is simply one or more consecutive lines of text, separated
1025 by one or more blank lines. (A blank line is any line that looks like a
1026 blank line -- a line containing nothing but spaces or tabs is considered
1027 blank.) Normal paragraphs should not be intended with spaces or tabs.
1029 The implication of the "one or more consecutive lines of text" rule is
1030 that Markdown supports "hard-wrapped" text paragraphs. This differs
1031 significantly from most other text-to-HTML formatters (including Movable
1032 Type's "Convert Line Breaks" option) which translate every line break
1033 character in a paragraph into a `<br />` tag.
1035 When you *do* want to insert a `<br />` break tag using Markdown, you
1036 end a line with two or more spaces, then type return.
1038 Yes, this takes a tad more effort to create a `<br />`, but a simplistic
1039 "every line break is a `<br />`" rule wouldn't work for Markdown.
1040 Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
1041 work best -- and look better -- when you format them with hard breaks.
1048 <h3 id="header">Headers</h3>
1050 Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
1052 Setext-style headers are "underlined" using equal signs (for first-level
1053 headers) and dashes (for second-level headers). For example:
1061 Any number of underlining `=`'s or `-`'s will work.
1063 Atx-style headers use 1-6 hash characters at the start of the line,
1064 corresponding to header levels 1-6. For example:
1070 ###### This is an H6
1072 Optionally, you may "close" atx-style headers. This is purely
1073 cosmetic -- you can use this if you think it looks better. The
1074 closing hashes don't even need to match the number of hashes
1075 used to open the header. (The number of opening hashes
1076 determines the header level.) :
1082 ### This is an H3 ######
1085 <h3 id="blockquote">Blockquotes</h3>
1087 Markdown uses email-style `>` characters for blockquoting. If you're
1088 familiar with quoting passages of text in an email message, then you
1089 know how to create a blockquote in Markdown. It looks best if you hard
1090 wrap the text and put a `>` before every line:
1092 > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
1093 > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
1094 > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
1096 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
1097 > id sem consectetuer libero luctus adipiscing.
1099 Markdown allows you to be lazy and only put the `>` before the first
1100 line of a hard-wrapped paragraph:
1102 > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
1103 consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
1104 Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
1106 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
1107 id sem consectetuer libero luctus adipiscing.
1109 Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
1110 adding additional levels of `>`:
1112 > This is the first level of quoting.
1114 > > This is nested blockquote.
1116 > Back to the first level.
1118 Blockquotes can contain other Markdown elements, including headers, lists,
1121 > ## This is a header.
1123 > 1. This is the first list item.
1124 > 2. This is the second list item.
1126 > Here's some example code:
1128 > return shell_exec("echo $input | $markdown_script");
1130 Any decent text editor should make email-style quoting easy. For
1131 example, with BBEdit, you can make a selection and choose Increase
1132 Quote Level from the Text menu.
1135 <h3 id="list">Lists</h3>
1137 Markdown supports ordered (numbered) and unordered (bulleted) lists.
1139 Unordered lists use asterisks, pluses, and hyphens -- interchangably
1158 Ordered lists use numbers followed by periods:
1164 It's important to note that the actual numbers you use to mark the
1165 list have no effect on the HTML output Markdown produces. The HTML
1166 Markdown produces from the above list is:
1174 If you instead wrote the list in Markdown like this:
1186 you'd get the exact same HTML output. The point is, if you want to,
1187 you can use ordinal numbers in your ordered Markdown lists, so that
1188 the numbers in your source match the numbers in your published HTML.
1189 But if you want to be lazy, you don't have to.
1191 If you do use lazy list numbering, however, you should still start the
1192 list with the number 1. At some point in the future, Markdown may support
1193 starting ordered lists at an arbitrary number.
1195 List markers typically start at the left margin, but may be indented by
1196 up to three spaces. List markers must be followed by one or more spaces
1199 To make lists look nice, you can wrap items with hanging indents:
1201 * Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
1202 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
1203 viverra nec, fringilla in, laoreet vitae, risus.
1204 * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
1205 Suspendisse id sem consectetuer libero luctus adipiscing.
1207 But if you want to be lazy, you don't have to:
1209 * Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
1210 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
1211 viverra nec, fringilla in, laoreet vitae, risus.
1212 * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
1213 Suspendisse id sem consectetuer libero luctus adipiscing.
1215 If list items are separated by blank lines, Markdown will wrap the
1216 items in `<p>` tags in the HTML output. For example, this input:
1237 <li><p>Bird</p></li>
1238 <li><p>Magic</p></li>
1241 List items may consist of multiple paragraphs. Each subsequent
1242 paragraph in a list item must be intended by either 4 spaces
1245 1. This is a list item with two paragraphs. Lorem ipsum dolor
1246 sit amet, consectetuer adipiscing elit. Aliquam hendrerit
1249 Vestibulum enim wisi, viverra nec, fringilla in, laoreet
1250 vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
1253 2. Suspendisse id sem consectetuer libero luctus adipiscing.
1255 It looks nice if you indent every line of the subsequent
1256 paragraphs, but here again, Markdown will allow you to be
1259 * This is a list item with two paragraphs.
1261 This is the second paragraph in the list item. You're
1262 only required to indent the first line. Lorem ipsum dolor
1263 sit amet, consectetuer adipiscing elit.
1265 * Another item in the same list.
1267 To put a blockquote within a list item, the blockquote's `>`
1268 delimiters need to be indented:
1270 * A list item with a blockquote:
1272 > This is a blockquote
1273 > inside a list item.
1275 To put a code block within a list item, the code block needs
1276 to be indented *twice* -- 8 spaces or two tabs:
1278 * A list item with a code block:
1283 It's worth noting that it's possible to trigger an ordered list by
1284 accident, by writing something like this:
1286 1986. What a great season.
1288 In other words, a *number-period-space* sequence at the beginning of a
1289 line. To avoid this, you can backslash-escape the period:
1291 1986\. What a great season.
1295 <h3 id="precode">Code Blocks</h3>
1297 Pre-formatted code blocks are used for writing about programming or
1298 markup source code. Rather than forming normal paragraphs, the lines
1299 of a code block are interpreted literally. Markdown wraps a code block
1300 in both `<pre>` and `<code>` tags.
1302 To produce a code block in Markdown, simply indent every line of the
1303 block by at least 4 spaces or 1 tab. For example, given this input:
1305 This is a normal paragraph:
1307 This is a code block.
1309 Markdown will generate:
1311 <p>This is a normal paragraph:</p>
1313 <pre><code>This is a code block.
1316 One level of indentation -- 4 spaces or 1 tab -- is removed from each
1317 line of the code block. For example, this:
1319 Here is an example of AppleScript:
1321 tell application "Foo"
1327 <p>Here is an example of AppleScript:</p>
1329 <pre><code>tell application "Foo"
1334 A code block continues until it reaches a line that is not indented
1335 (or the end of the article).
1337 Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
1338 are automatically converted into HTML entities. This makes it very
1339 easy to include example HTML source code using Markdown -- just paste
1340 it and indent it, and Markdown will handle the hassle of encoding the
1341 ampersands and angle brackets. For example, this:
1343 <div class="footer">
1344 © 2004 Foo Corporation
1349 <pre><code><div class="footer">
1350 &copy; 2004 Foo Corporation
1354 Regular Markdown syntax is not processed within code blocks. E.g.,
1355 asterisks are just literal asterisks within a code block. This means
1356 it's also easy to use Markdown to write about Markdown's own syntax.
1360 <h3 id="hr">Horizontal Rules</h3>
1362 You can produce a horizontal rule tag (`<hr />`) by placing three or
1363 more hyphens, asterisks, or underscores on a line by themselves. If you
1364 wish, you may use spaces between the hyphens or asterisks. Each of the
1365 following lines will produce a horizontal rule:
1375 ---------------------------------------
1382 <h2 id="span">Span Elements</h2>
1384 <h3 id="link">Links</h3>
1386 Markdown supports two style of links: *inline* and *reference*.
1388 In both styles, the link text is delimited by [square brackets].
1390 To create an inline link, use a set of regular parentheses immediately
1391 after the link text's closing square bracket. Inside the parentheses,
1392 put the URL where you want the link to point, along with an *optional*
1393 title for the link, surrounded in quotes. For example:
1395 This is [an example](http://example.com/ "Title") inline link.
1397 [This link](http://example.net/) has no title attribute.
1401 <p>This is <a href="http://example.com/" title="Title">
1402 an example</a> inline link.</p>
1404 <p><a href="http://example.net/">This link</a> has no
1405 title attribute.</p>
1407 If you're referring to a local resource on the same server, you can
1410 See my [About](/about/) page for details.
1412 Reference-style links use a second set of square brackets, inside
1413 which you place a label of your choosing to identify the link:
1415 This is [an example][id] reference-style link.
1417 You can optionally use a space to separate the sets of brackets:
1419 This is [an example] [id] reference-style link.
1421 Then, anywhere in the document, you define your link label like this,
1422 on a line by itself:
1424 [id]: http://example.com/ "Optional Title Here"
1428 * Square brackets containing the link identifier (optionally
1429 indented from the left margin using up to three spaces);
1430 * followed by a colon;
1431 * followed by one or more spaces (or tabs);
1432 * followed by the URL for the link;
1433 * optionally followed by a title attribute for the link, enclosed
1434 in double or single quotes.
1436 The link URL may, optionally, be surrounded by angle brackets:
1438 [id]: <http://example.com/> "Optional Title Here"
1440 You can put the title attribute on the next line and use extra spaces
1441 or tabs for padding, which tends to look better with longer URLs:
1443 [id]: http://example.com/longish/path/to/resource/here
1444 "Optional Title Here"
1446 Link definitions are only used for creating links during Markdown
1447 processing, and are stripped from your document in the HTML output.
1449 Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
1456 The *implicit link name* shortcut allows you to omit the name of the
1457 link, in which case the link text itself is used as the name.
1458 Just use an empty set of square brackets -- e.g., to link the word
1459 "Google" to the google.com web site, you could simply write:
1463 And then define the link:
1465 [Google]: http://google.com/
1467 Because link names may contain spaces, this shortcut even works for
1468 multiple words in the link text:
1470 Visit [Daring Fireball][] for more information.
1472 And then define the link:
1474 [Daring Fireball]: http://daringfireball.net/
1476 Link definitions can be placed anywhere in your Markdown document. I
1477 tend to put them immediately after each paragraph in which they're
1478 used, but if you want, you can put them all at the end of your
1479 document, sort of like footnotes.
1481 Here's an example of reference links in action:
1483 I get 10 times more traffic from [Google] [1] than from
1484 [Yahoo] [2] or [MSN] [3].
1486 [1]: http://google.com/ "Google"
1487 [2]: http://search.yahoo.com/ "Yahoo Search"
1488 [3]: http://search.msn.com/ "MSN Search"
1490 Using the implicit link name shortcut, you could instead write:
1492 I get 10 times more traffic from [Google][] than from
1493 [Yahoo][] or [MSN][].
1495 [google]: http://google.com/ "Google"
1496 [yahoo]: http://search.yahoo.com/ "Yahoo Search"
1497 [msn]: http://search.msn.com/ "MSN Search"
1499 Both of the above examples will produce the following HTML output:
1501 <p>I get 10 times more traffic from <a href="http://google.com/"
1502 title="Google">Google</a> than from
1503 <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
1504 or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
1506 For comparison, here is the same paragraph written using
1507 Markdown's inline link style:
1509 I get 10 times more traffic from [Google](http://google.com/ "Google")
1510 than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
1511 [MSN](http://search.msn.com/ "MSN Search").
1513 The point of reference-style links is not that they're easier to
1514 write. The point is that with reference-style links, your document
1515 source is vastly more readable. Compare the above examples: using
1516 reference-style links, the paragraph itself is only 81 characters
1517 long; with inline-style links, it's 176 characters; and as raw HTML,
1518 it's 234 characters. In the raw HTML, there's more markup than there
1521 With Markdown's reference-style links, a source document much more
1522 closely resembles the final output, as rendered in a browser. By
1523 allowing you to move the markup-related metadata out of the paragraph,
1524 you can add links without interrupting the narrative flow of your
1528 <h3 id="em">Emphasis</h3>
1530 Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
1531 emphasis. Text wrapped with one `*` or `_` will be wrapped with an
1532 HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
1533 `<strong>` tag. E.g., this input:
1537 _single underscores_
1539 **double asterisks**
1541 __double underscores__
1545 <em>single asterisks</em>
1547 <em>single underscores</em>
1549 <strong>double asterisks</strong>
1551 <strong>double underscores</strong>
1553 You can use whichever style you prefer; the lone restriction is that
1554 the same character must be used to open and close an emphasis span.
1556 Emphasis can be used in the middle of a word:
1558 un*fucking*believable
1560 But if you surround an `*` or `_` with spaces, it'll be treated as a
1561 literal asterisk or underscore.
1563 To produce a literal asterisk or underscore at a position where it
1564 would otherwise be used as an emphasis delimiter, you can backslash
1567 \*this text is surrounded by literal asterisks\*
1571 <h3 id="code">Code</h3>
1573 To indicate a span of code, wrap it with backtick quotes (`` ` ``).
1574 Unlike a pre-formatted code block, a code span indicates code within a
1575 normal paragraph. For example:
1577 Use the `printf()` function.
1581 <p>Use the <code>printf()</code> function.</p>
1583 To include a literal backtick character within a code span, you can use
1584 multiple backticks as the opening and closing delimiters:
1586 ``There is a literal backtick (`) here.``
1588 which will produce this:
1590 <p><code>There is a literal backtick (`) here.</code></p>
1592 The backtick delimiters surrounding a code span may include spaces --
1593 one after the opening, one before the closing. This allows you to place
1594 literal backtick characters at the beginning or end of a code span:
1596 A single backtick in a code span: `` ` ``
1598 A backtick-delimited string in a code span: `` `foo` ``
1602 <p>A single backtick in a code span: <code>`</code></p>
1604 <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
1606 With a code span, ampersands and angle brackets are encoded as HTML
1607 entities automatically, which makes it easy to include example HTML
1608 tags. Markdown will turn this:
1610 Please don't use any `<blink>` tags.
1614 <p>Please don't use any <code><blink></code> tags.</p>
1618 `—` is the decimal-encoded equivalent of `—`.
1622 <p><code>&#8212;</code> is the decimal-encoded
1623 equivalent of <code>&mdash;</code>.</p>
1627 <h3 id="img">Images</h3>
1629 Admittedly, it's fairly difficult to devise a "natural" syntax for
1630 placing images into a plain text document format.
1632 Markdown uses an image syntax that is intended to resemble the syntax
1633 for links, allowing for two styles: *inline* and *reference*.
1635 Inline image syntax looks like this:
1637 ![Alt text](/path/to/img.jpg)
1639 ![Alt text](/path/to/img.jpg "Optional title")
1643 * An exclamation mark: `!`;
1644 * followed by a set of square brackets, containing the `alt`
1645 attribute text for the image;
1646 * followed by a set of parentheses, containing the URL or path to
1647 the image, and an optional `title` attribute enclosed in double
1650 Reference-style image syntax looks like this:
1654 Where "id" is the name of a defined image reference. Image references
1655 are defined using syntax identical to link references:
1657 [id]: url/to/image "Optional title attribute"
1659 As of this writing, Markdown has no syntax for specifying the
1660 dimensions of an image; if this is important to you, you can simply
1661 use regular HTML `<img>` tags.
1667 <h2 id="misc">Miscellaneous</h2>
1669 <h3 id="autolink">Automatic Links</h3>
1671 Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
1673 <http://example.com/>
1675 Markdown will turn this into:
1677 <a href="http://example.com/">http://example.com/</a>
1679 Automatic links for email addresses work similarly, except that
1680 Markdown will also perform a bit of randomized decimal and hex
1681 entity-encoding to help obscure your address from address-harvesting
1682 spambots. For example, Markdown will turn this:
1684 <address@example.com>
1686 into something like this:
1688 <a href="mailto:addre
1689 ss@example.co
1690 m">address@exa
1691 mple.com</a>
1693 which will render in a browser as a clickable link to "address@example.com".
1695 (This sort of entity-encoding trick will indeed fool many, if not
1696 most, address-harvesting bots, but it definitely won't fool all of
1697 them. It's better than nothing, but an address published in this way
1698 will probably eventually start receiving spam.)
1702 <h3 id="backslash">Backslash Escapes</h3>
1704 Markdown allows you to use backslash escapes to generate literal
1705 characters which would otherwise have special meaning in Markdown's
1706 formatting syntax. For example, if you wanted to surround a word with
1707 literal asterisks (instead of an HTML `<em>` tag), you can backslashes
1708 before the asterisks, like this:
1710 \*literal asterisks\*
1712 Markdown provides backslash escapes for the following characters:
1723 - minus sign (hyphen)
1728 The operating system wars are still going, they've just taken on a new form: the
1729 ecosystems of major software development centers like microsoft, facebook,
1730 google, apple, amazon, have just become the new battleground. All of these
1731 ecosystems are seeking to replace the entire unix operating system stack with
1732 their own internal APIs and code. from writing code in awk/sed/bash to utilize
1733 the OS's commands as an api, to generalizing this in python-esque languages, and
1734 now to new programming frameworks for every language which package endless
1735 libraries that are just sloppy new rewrites of decades-old functionality already
1736 in the GNU environment. the good news is that there's a ton of energy going into
1737 language research, compilers, and there are many new emerging standards as a
1738 result for message sending (alan kay "real objects"), network federation,
1739 package management, build tools, live coding, web technology, execution
1740 platforms, and everything in between. the bad news is that basically all energy
1741 is just going towards building, and rebuilding, and rebuilding application
1742 frameworks. Call them libraries, packages, eggs, utilities, or whatever, they're
1743 all just another incomplete rewrite of tools that have been around and
1744 maintained for over half a century. They're easier to use, which is great, but
1745 that user interface (i.e. language syntax and package management) doesn't need
1746 to be divorced from existing functionality. As far as I can figure, it's just
1747 gouche, or somehow seen as less sophisticated and interesting, if a language
1748 keeps C dependencies after a certain point. Almost all languages start out their
1749 life as C programs, and it's considered a major milestone when the language's
1750 compiler can finally compile itself and become self-hosting. All this proves is
1751 that the language can generate a compiler, though. It's a sloppy metric of
1752 progress. It's another major milestone when the language's libraries no longer
1753 have any C library dependencies (i.e. all commonly used APIs for handling i18n,
1754 unicode, hashtables, etcetera, have been reinvented in the new
1755 language). And perhaps its greatest achievement of all is to remove dependence
1756 on libc - the single most rugged and well-tested system interface on the
1759 What I'd really like to see is a language that