您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

migrate-from-jekyll.md 6.9KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. ---
  2. title: "Migrate from Jekyll"
  3. date: 2014-03-10
  4. tags: ["go", "golang", "hugo", "jekyll", "static-site-generator"]
  5. draft: false
  6. ---
  7. ## Move static content to `static`
  8. Jekyll has a rule that any directory not starting with `_` will be copied as-is to the `_site` output. Hugo keeps all static content under `static`. You should therefore move it all there.
  9. With Jekyll, something that looked like
  10. ▾ <root>/
  11. ▾ images/
  12. logo.png
  13. should become
  14. ▾ <root>/
  15. ▾ static/
  16. ▾ images/
  17. logo.png
  18. Additionally, you'll want any files that should reside at the root (such as `CNAME`) to be moved to `static`.
  19. ## Create your Hugo configuration file
  20. Hugo can read your configuration as JSON, YAML or TOML. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.
  21. ## Set your configuration publish folder to `_site`
  22. The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:
  23. 1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).
  24. git submodule deinit _site
  25. git rm _site
  26. git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
  27. 2. Or, change the Hugo configuration to use `_site` instead of `public`.
  28. {
  29. ..
  30. "publishdir": "_site",
  31. ..
  32. }
  33. ## Convert Jekyll templates to Hugo templates
  34. That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.
  35. As a single reference data point, converting my templates for [heyitsalex.net](http://heyitsalex.net/) took me no more than a few hours.
  36. ## Convert Jekyll plugins to Hugo shortcodes
  37. Jekyll has [plugins](http://jekyllrb.com/docs/plugins/); Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.
  38. ### Implementation
  39. As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.
  40. Jekyll's plugin:
  41. module Jekyll
  42. class ImageTag < Liquid::Tag
  43. @url = nil
  44. @caption = nil
  45. @class = nil
  46. @link = nil
  47. // Patterns
  48. IMAGE_URL_WITH_CLASS_AND_CAPTION =
  49. IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i
  50. IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
  51. IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
  52. IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
  53. def initialize(tag_name, markup, tokens)
  54. super
  55. if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
  56. @class = $1
  57. @url = $3
  58. @caption = $7
  59. @link = $9
  60. elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
  61. @class = $1
  62. @url = $3
  63. @caption = $7
  64. elsif markup =~ IMAGE_URL_WITH_CAPTION
  65. @url = $1
  66. @caption = $5
  67. elsif markup =~ IMAGE_URL_WITH_CLASS
  68. @class = $1
  69. @url = $3
  70. elsif markup =~ IMAGE_URL
  71. @url = $1
  72. end
  73. end
  74. def render(context)
  75. if @class
  76. source = "<figure class='#{@class}'>"
  77. else
  78. source = "<figure>"
  79. end
  80. if @link
  81. source += "<a href=\"#{@link}\">"
  82. end
  83. source += "<img src=\"#{@url}\">"
  84. if @link
  85. source += "</a>"
  86. end
  87. source += "<figcaption>#{@caption}</figcaption>" if @caption
  88. source += "</figure>"
  89. source
  90. end
  91. end
  92. end
  93. Liquid::Template.register_tag('image', Jekyll::ImageTag)
  94. is written as this Hugo shortcode:
  95. <!-- image -->
  96. <figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
  97. {{ with .Get "link"}}<a href="{{.}}">{{ end }}
  98. <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
  99. {{ if .Get "link"}}</a>{{ end }}
  100. {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
  101. <figcaption>{{ if isset .Params "title" }}
  102. {{ .Get "title" }}{{ end }}
  103. {{ if or (.Get "caption") (.Get "attr")}}<p>
  104. {{ .Get "caption" }}
  105. {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
  106. {{ .Get "attr" }}
  107. {{ if .Get "attrlink"}}</a> {{ end }}
  108. </p> {{ end }}
  109. </figcaption>
  110. {{ end }}
  111. </figure>
  112. <!-- image -->
  113. ### Usage
  114. I simply changed:
  115. {% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
  116. to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):
  117. {{%/* fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" */%}}
  118. As a bonus, the shortcode named parameters are, arguably, more readable.
  119. ## Finishing touches
  120. ### Fix content
  121. Depending on the amount of customization that was done with each post with Jekyll, this step will require more or less effort. There are no hard and fast rules here except that `hugo server --watch` is your friend. Test your changes and fix errors as needed.
  122. ### Clean up
  123. You'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.
  124. ## A practical example in a diff
  125. [Hey, it's Alex](http://heyitsalex.net/) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).