octopress-multilingual 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93762ea4b72fa9617cb1a1e6517f07c7286bc84f
-  data.tar.gz: cec1457c4daaf7614f0baccd33aa100f623e760b
+  metadata.gz: d574450d03a50e29229defe0ea43f9aa62c8052f
+  data.tar.gz: 1a3203980d28af20e8bf76494680d069f3eec942
 SHA512:
-  metadata.gz: 778acd242ccea05e7f555d84e820613a6156b0c41399d2e1c5af0714645b9f687094260511cb59bd5699372f54f946d8db3b82da9527f6e2a99235ebc35f1a95
-  data.tar.gz: e74201756fed2707d1a499b1d3d26ea30fe66e4b7f866f6593955bf33d34ab3114f4954b0b7a1a091725c67b83d3585f6ddc36cfa404b7e404f0ec863d892f1b
+  metadata.gz: 12682c041d6f53e83c69ec5f42de3494efa574a472c5e4e6a09b717bbb82b03d19f32dcc8228df1ea9d6dc6ea578bd19a18a62eaf462c2356902341c8cad8952
+  data.tar.gz: 18361af1f5d6b236060a2314c9390121566908b36939c78ae70c53aa0dd10368ff38577d71a032d7d633ad1635629b728b3edb3fec7524d3dc0e21cc63465c78

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+### 0.1.0 (2015-01-30)
+- Change: No longer filters `site.posts` at all.
+- Change: Posts are automatically filtered based on `page.lang`.
+- Docs have been improved quite a bit.
+
 ### 0.0.9 (2015-01-25)
 - Fix: Language cross-posts are now properly sorted. Thanks @drallgood, via [#6](https://github.com/octopress/multilingual/pull/6).
 

data/README.md

@@ -1,6 +1,10 @@
 # Octopress Multilingual
 
-Add multiple language features to your Jekyll site.
+Add multiple language features to your Jekyll site. This plugin makes it easy to:
+
+- Add language-specific post indexes, archives, and RSS feeds.
+- Set language based permalinks. 
+- Cross-post between languages.
 
 [![Build Status](http://img.shields.io/travis/octopress/multilingual.svg)](https://travis-ci.org/octopress/multilingual)
 [![Gem Version](http://img.shields.io/gem/v/octopress-multilingual.svg)](https://rubygems.org/gems/octopress-multilingual)
@@ -30,11 +34,15 @@ Then add the gem to your Jekyll configuration.
 
 ## An important note
 
-**There is not a Jekyll standard for multilingual sites** and many plugins will not work properly with this setup. Octopress and it's
+**There is no Jekyll standard for multilingual sites** and many plugins will not work properly with this setup. Octopress and it's
 plugins are being designed to support multilingual features, but without a standard, some use-cases may be overlooked. If you have a
 problem with an Octopress plugin supporting your multilingual site, please file an issue and we'll do our best to address it.
 
-## Setting up a multilingual site
+Note: First-party Octopress plugins are designed to support multilingual sites but other plugins may not work how you'd expect on multilingual sites. Modifying plugins is beyond the scope of this guide.
+
+Also, if you are using flags to represent languages on your site, you might like to read, [Why flags do not represent language](http://flagsarenotlanguages.com/blog/why-flags-do-not-represent-language/).
+
+## Setup
 
 When adding this plugin to your site, you will need to:
 
@@ -42,14 +50,6 @@ When adding this plugin to your site, you will need to:
 2. Add a language to the YAML front-matter of your posts, e.g. `lang: de`.
 3. Add new RSS feeds and post indexes for secondary languages.
 
-Read on and I'll try to walk you through setting up your multilingual site.
-
-Note: This guide will only cover the steps listed above. Your site may still have some plugins which are not designed for multilingual sites. If you are using plugins (like a category index generator) which create pages from your site's posts, they may need to be modified or removed. Modifying plugins is beyond the scope of this guide.
-
-## Configuration
-
-You can  for standard language codes.
-
 First, be sure to configure your Jekyll site's main language. An site written primarily in English would add this to its Jekyll configuration:
 
 ```yaml
@@ -57,36 +57,86 @@ lang: en
 ```
 
 Here we are setting the default language to English. Posts without a defined language will be treated as English posts.
-For a list of standard language codes, refer to [ISO 639-1](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
+For a list of standard language codes, refer to [ISO 639-1](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). You can also use
+the [language]-[region] method of setting your site's language, like `en-us` for American English or `de-at` for Austrian German.
 
-## Defining a post's language
+### Setting a language for pages or posts
 
-Posts should specify their language in the YAML front matter.
+Specify a page or post's language in the YAML front matter.
 
 ```yaml
 title: "Ein nachdenklicher Beitrag"
 lang: de
 ```
 
-If you are using Octopress, you can easily create a new post with the language already site like this:
+With Octopress, you can do this automatically from the command line when creating posts, drafts, or pages.
 
 ```
 $ octopress new post "Some title" --lang en
+$ octopress new draft "Some title" --lang en
+$ octopress new page de/index.html --lang de
+```
+
+This command will set the language (in the YAML front-matter) and posts will be created in `_posts/[lang]/[post-file]`.
+
+## Indexes, RSS feeds and Archives.
+
+If you are writing English and German posts, you'll want an English-only and a German-only post index. To do that, just set the
+language in the YAML front-matter of your post-index. 
+
+For example, this will loop through only German posts:
+
+```
+---
+lang: de
+---
+{% for post in site.posts %} ... {% endfor %}
+```
+
+And this will loop through only English posts:
+
+```
+---
+lang: en
+---
+{% for post in site.posts %} ... {% endfor %}
 ```
 
-This command will set the post language (in the YAML front-matter) and add it to the `_posts/en` directory.
+If your default post index is at `/index.html` you should create additional indexes for each secondary language. If your secondary language is German, create a posts index at `/de/index.html`.
+
+How does it work? First this plugin groups all of your posts by language. Then at build time, any page with a language defined will
+have its posts filtered to display only matching languages. If your site uses [octopress-linkblog](https://github.com/octopress/linkblog) to publish link-posts, your `site.articles` and `site.linkposts` will be filtered as well.
+
+This same approach will let you create language-specific RSS feeds and post archives. If you are using [octopress-feeds](https://github.com/octopress/feeds), the default RSS feeds will automatically use your default `site.lang` defined language and you can easily create additional RSS feeds for additional languages.
+
+## Reference posts by language
+
+All posts are grouped by language and can be accessed directly with `site.posts_by_language`. For example:
+
+```
+{% for post in site.posts_by_language.de %}  # German posts
+{% for post in site.posts_by_language.en %}  # English posts
+```
+
+If you have [octopress-linkblog](https://github.com/octopress/linkblog) installed, you can access groups of link-posts and articles too.
+
+```
+{% for post in site.linkposts_by_language.de %}  # German linkposts
+{% for post in site.articles_by_language.de %}   # German articles
+```
 
 ### Cross-posting languages
 
-Occasionally you may wish to write a post in a single language and have it show up in other languages indexes and feeds. This can be done in your post's YAML front-matter:
+If you would like to write a post which shows up in indexes and feeds for every language, set `lang: all` in your post's YAML
+front-matter.
 
 ```
 title: "Ein nachdenklicher Beitrag"
-lang: de
-crosspost_languages: true
+lang: all
 ```
 
-If your site has language-specific feeds or post indexes, a post with this setting will show up in all of them. However, it isn't duplicated. It will still have one canonical URL.
+This post will show up with every language. However, it will be treated exactly like a post written in your
+site's default language and will have one canonical URL. Even `{{ post.lang }}` will return your default language instead of `all`.
 
 ### Language in permalinks
 
@@ -118,100 +168,39 @@ ordinal => /:lang/:categories/:year/:y_day/:title.html
 
 If you don't want language to appear in your URLs, you must configure your own permalinks without `:lang`.
 
-## Changing language scope
 
-This plugin modifies your site's post list. The `site.posts` array **will not contain every post**, but only posts defined with your site's main language or with no language defined.
+## Temporary language scoping
 
 Using the `set_lang` liquid block, you can temporarily switch languages while rendering a portion of your site. For example:
 
 ```
-{{ site.lang }}    # => 'en'
-{{ site.posts }}   # => English posts
+{{ page.lang }}    # => 'en'
+{{ site.posts }}   # => All posts
 
 {% set_lang de %}
-  {{ site.lang }}  # => 'de'
+  {{ page.lang }}  # => 'de'
   {{ site.posts }} # => German posts
 {% endset_lang %}
 
-{{ site.lang }}    # => 'en'
-{{ site.posts }}   # => English posts
+{{ page.lang }}    # => 'en'
+{{ site.posts }}   # => All posts
 ```
 
-If you have the [octopress-linkblog](https://github.com/octopress/linkblog) plugin installed, this will also change scope for your
-`site.articles` and `site.linkposts` loops.
+The `set_lang` tag will also accept variables, for example:
 
-## Post Indexes and RSS Feeds
-
-To add multilingual post indexes you can use the `set_lang` tag like this:
-
-```
-{% set_lang de %}
-{% for post in site.posts %}...{% endfor %}
-{% endset_lang %}
 ```
+{% assign lang = 'de' %}
+{% set_lang lang %}   # equivilent to {% set_lang de %}
 
-If your default post index is at `/index.html` you should create additional indexes for each secondary language. If you're also writing in German, create a posts index at `/de/index.html`.
-
-DRY up your templates by putting post loops in an include, for
-example, `_includes/post-index.html`. It might look this:
-
-<!-- title:"From _includes/post-index.html" -->
-```
-{% set_lang page.lang %}
-{% for post in site.posts %}...{% endfor %}
-{% endset_lang %}
-```
-
-Set the page language to German and include the same partial.
-
-<!-- title:"From /de/index.html" -->
-```
----
-lang: de
----
-{% include post-index.html %}
-```
-
-The `set_lang` tag will read the `page.lang` setting and
-convert the post loop to use German. If `page.lang` were
-`nil` the default language will be used.
-
-If you don't want to set the `lang` for a page, but want to
-use `{% set_lang %}`, that's fine too. It will also work like
-this:
+# On some page
+{% include some_partial.html lang='de' %}
 
+# In _includes/some_partial.html
+{% set_lang include.lang %}    # equivilent to {% set_lang de %} 
 ```
-{% include post-index.html lang='de' %}
 
-# Then in the included partial
-{% set_lang include.lang %}
-...
-```
-
-Or even just use a normal post loop on your included file and
-set the language when including the partial.
-
-```
-{% set_lang de %}{% include post-index.html %}{% endset_lang %}
-```
-
-There are lots of ways to use this, but this approach should work for RSS feeds or any template system which works with the post loop.
-
-## Reference posts by language
-
-You may also access secondary languages directly with `site.posts_by_language`.
-
-For example, to loop through the posts written in your main language (or those with no defined language) you would do this:
-
-```
-{% for post in site.posts %}
-```
-
-If you want to loop through the posts from a secondary language — in this case, German — you would want to do this:
-
-```
-{% for post in site.posts_by_language.de %}
-```
+If you have the [octopress-linkblog](https://github.com/octopress/linkblog) plugin installed, this will also change languages for your
+`site.articles` and `site.linkposts` loops.
 
 ## Contributing
 

data/lib/octopress-multilingual.rb

@@ -1,11 +1,14 @@
+require 'octopress-hooks'
+
 require "octopress-multilingual/version"
 require "octopress-multilingual/set_lang-tag"
-require 'octopress-hooks'
+require "octopress-multilingual/hooks"
+require "octopress-multilingual/jekyll"
 
 module Octopress
   module Multilingual
     extend self
-    attr_accessor :site, :posts
+    attr_accessor :site
 
     def main_language
       if @lang ||= site.config['lang']
@@ -16,18 +19,19 @@ module Octopress
              << "  lang: en\n\n"
       end
     end
-    
+
     def languages
       posts_by_language.keys
     end
 
     def posts_by_language
-      @posts_by_language ||= begin 
-        posts = site.posts.reverse.select(&:lang).group_by(&:lang) \
+      @posts_by_language ||= begin
+        posts = site.posts.reverse.select(&:lang).group_by(&:lang)
         ## Add posts that crosspost to all languages
-        .each do |lang, posts|
+        
+        posts.each do |lang, lang_posts|
           if lang != main_language
-            posts.concat(crossposts).sort_by!(&:date).reverse!
+            lang_posts.concat(crossposts).sort_by!(&:date).reverse!
           end
         end
 
@@ -37,17 +41,13 @@ module Octopress
       end
     end
 
-    def main_language_posts
-      site.posts.reverse.reject do |post|
-        post.lang && post.lang != main_language
-      end
+    def crossposts
+      site.posts.select(&:language_crosspost)
     end
 
-    def crossposts
-      @cross_posts ||= begin
-        posts = site.posts.reverse.select do |post|
-          post.data['crosspost_languages']
-        end
+    def main_language_posts
+      site.posts.reverse.select do |post|
+        post.lang.nil? || post.lang == main_language
       end
     end
 
@@ -55,34 +55,8 @@ module Octopress
       @posts_without_lang ||= site.reject(&:lang)
     end
 
-    def site_payload
-      if defined?(Octopress::Docs) && Octopress::Docs.enabled?
-        {}
-      else
-        return unless main_language
-
-        @payload ||= begin
-          payload = {
-            'posts'             => main_language_posts,
-            'posts_by_language' => posts_by_language,
-            'languages'         => languages
-          }
-
-          if defined? Octopress::Linkblog
-            payload.merge!({
-              'linkposts' => linkposts_by_language[main_language],
-              'articles'  => articles_by_language[main_language],
-              'linkposts_by_language' => linkposts_by_language,
-              'articles_by_language' => articles_by_language
-            })
-          end
-          payload
-        end
-      end
-    end
-
     def articles_by_language
-      @articles_by_language ||= begin 
+      @articles_by_language ||= begin
         articles = {}
 
         languages.each do |lang|
@@ -96,7 +70,7 @@ module Octopress
     end
 
     def linkposts_by_language
-      @linkposts_by_language ||= begin 
+      @linkposts_by_language ||= begin
         linkposts = {}
 
         languages.each do |lang|
@@ -109,97 +83,45 @@ module Octopress
       end
     end
 
-    class SiteHookRead < Hooks::Site
-      priority :high
-      # Generate site_payload so other plugins can access 
-      def post_read(site)
-        Octopress::Multilingual.site = site 
-      end
-    end
-
-    class SiteHook < Hooks::Site
-      priority :low
-
-      def merge_payload(payload, site)
-
-        # Group posts by language, { 'en_post' => [posts,..] }
-        #
-
-        # Ensure that posts without an assigned language
-        # appear in each language's feed
-        #
-        
-        { 
-          'site' => Octopress::Multilingual.site_payload,
-        }
-      end
-    end
-  end
-end
-
-module Jekyll
-  class URL
-    def generate_url(template)
-      @placeholders.inject(template) do |result, token|
-        break result if result.index(':').nil? 
-        if token.last.nil?
-          result.gsub(/\/:#{token.first}/, '')
-        else
-          result.gsub(/:#{token.first}/, self.class.escape_path(token.last))
-        end
-      end
-    end
-  end
-
-  class Post
-    alias :template_orig :template
-    alias :url_placeholders_orig :url_placeholders 
-    
-    def template
-      template = template_orig
+    def page_payload(lang)
+      payload = { 'posts' => posts_by_language[lang] }
 
-      if [:pretty, :none, :date, :ordinal].include? site.permalink_style
-        template = File.join('/:lang', template)
+      # If the octopress-linkblog plugin is installed swap out articles and linkposts
+      #
+      if defined? Octopress::Linkblog
+        payload['linkposts'] = linkposts_by_language[lang]
+        payload['articles']  = articles_by_language[lang]
       end
 
-      template
+      payload
     end
 
-    def lang
-      data['lang'].downcase if data['lang'] 
-    end
+    def site_payload
+      # Skip when when showing documentation site
+      if defined?(Octopress::Docs) && Octopress::Docs.enabled?
+        {}
+      else
+        return unless main_language
 
-    def url_placeholders
-      url_placeholders_orig.merge({
-        :lang => lang
-      })
-    end
+        @payload ||= begin
+          payload = {
+            'posts_by_language' => posts_by_language,
+            'languages'         => languages
+          }
 
-    def next
-      language = lang || site.config['lang']
-      posts = Octopress::Multilingual.posts_by_language[language] 
-      pos = posts.index {|post| post.equal?(self) }
-      if pos && pos < posts.length - 1
-        posts[pos + 1]
-      else
-        nil
-      end
-    end
+          if defined? Octopress::Linkblog
+            payload['linkposts_by_language'] = linkposts_by_language
+            payload['articles_by_language']  = articles_by_language
+          end
 
-    def previous
-      language = lang || site.config['lang']
-      posts = Octopress::Multilingual.posts_by_language[language] 
-      pos = posts.index {|post| post.equal?(self) }
-      if pos && pos > 0
-        posts[pos - 1]
-      else
-        nil
+          payload
+        end
       end
     end
-    
   end
 end
 
+
 if defined? Octopress::Docs
   Octopress::Docs.add({
     name:        "Octopress Multilingual",

data/lib/octopress-multilingual/hooks.rb

@@ -0,0 +1,34 @@
+module Octopress
+  module Multilingual
+    class SiteHookRead < Hooks::Site
+      priority :high
+      # Generate site_payload so other plugins can access
+      def post_read(site)
+        Octopress::Multilingual.site = site
+      end
+    end
+
+    class SiteHook < Hooks::Site
+      # Use a low priority so that other hooks can act on posts
+      # without having to be designed for mutlilingual sites.
+      priority :high
+
+      #
+      def merge_payload(payload, site)
+        { 'site' => Octopress::Multilingual.site_payload }
+      end
+    end
+
+    class PagePayloadHook < Hooks::All
+      priority :high
+
+      # Swap out post arrays with posts of the approrpiate language
+      #
+      def merge_payload(payload, item)
+        if item.lang
+          { 'site' => Octopress::Multilingual.page_payload(item.lang) }
+        end
+      end
+    end
+  end
+end

data/lib/octopress-multilingual/jekyll.rb

@@ -0,0 +1,94 @@
+module Jekyll
+  class URL
+    def generate_url(template)
+      @placeholders.inject(template) do |result, token|
+        break result if result.index(':').nil?
+        if token.last.nil?
+          result.gsub(/\/:#{token.first}/, '')
+        else
+          result.gsub(/:#{token.first}/, self.class.escape_path(token.last))
+        end
+      end
+    end
+  end
+
+  class Document
+    def lang
+      if data['lang']
+        data['lang'].downcase
+      end
+    end
+  end
+
+  class Page
+    def lang
+      if data['lang']
+        if data['lang'].downcase == 'default'
+          data['lang'] == site.lang
+        end
+        data['lang'].downcase
+      end
+    end
+  end
+
+  class Post
+    alias :template_orig :template
+    alias :url_placeholders_orig :url_placeholders
+
+    def template
+      template = template_orig
+
+      if [:pretty, :none, :date, :ordinal].include? site.permalink_style
+        template = File.join('/:lang', template)
+      end
+
+      template
+    end
+
+    def lang
+      if data['lang']
+        if data['lang'].downcase == 'all'
+          @language_crosspost = true
+          data['lang'] = site.config['lang']
+        end
+        data['lang'].downcase
+      end
+    end
+
+    def language_crosspost
+      @language_crosspost if lang
+    end
+
+    def url_placeholders
+
+      url_placeholders_orig.merge({
+        :lang => lang
+      })
+    end
+
+    def next
+      language = lang || site.config['lang']
+      posts = Octopress::Multilingual.posts_by_language[language]
+
+      pos = posts.index {|post| post.equal?(self) }
+      if pos && pos < posts.length - 1
+        posts[pos + 1]
+      else
+        nil
+      end
+    end
+
+    def previous
+      language = lang || site.config['lang']
+      posts = Octopress::Multilingual.posts_by_language[language]
+
+      pos = posts.index {|post| post.equal?(self) }
+      if pos && pos > 0
+        posts[pos - 1]
+      else
+        nil
+      end
+    end
+  end
+end
+

data/lib/octopress-multilingual/set_lang-tag.rb

@@ -9,35 +9,33 @@ module Octopress
       end
 
       def render(context)
-        @context     = context
-        @languages   = @context['site.languages']
-        @lang_posts  = @context['site.posts_by_language']
-        main_lang   = @context['site.lang']
+        @context         = context
+        @languages       = @context['site.languages']
 
-        # Render with new posts context
-        if lang
+        # If a language is defined
+        if lang && lang != @context['page.lang']
 
-          # Set to specified language
-          set_post_lang lang
-          set_current_lang(lang)
-
-          # Render
-          content = super(context)
-
-          # Reset to main language
-          set_post_lang main_lang
-          set_current_lang(main_lang)
+          store_state                    # Store current language and post arrays
+          set_lang lang                  # Set to specified language
+          content = super(context)       # Render
+          restore_state                  # Restore language and post arrays
 
           content
         else
-          # Tell scope it's in the main
+          # If the language argument resovles to nil
+          # this will render contents normally
+          # 
           super(context)
         end
       end
 
-      def set_post_lang(lang)
+      # Swap out site.posts, site.linkposts, and site.articles with
+      # arrays filtered by the selected language
+      #
+      def set_lang(lang)
+        @context.environments.first['page']['lang'] = lang
         site = @context.environments.first['site']
-        site['posts'] = @lang_posts[lang]
+        site['posts'] = site['posts_by_language'][lang]
 
         if defined? Octopress::Linkblog
           site['linkposts'] = site['linkposts_by_language'][lang]
@@ -45,14 +43,36 @@ module Octopress
         end
       end
 
-      def set_current_lang(lang)
-        @context.environments.first['site']['lang'] = lang
+      def store_state
+        @current_lang       = @context['page.lang']
+        @posts              = @context['site.posts']
+
+        if defined? Octopress::Linkblog
+          @articles         = @context['site.articles']
+          @links            = @context['site.linkposts']
+        end
+      end
+
+      def restore_state
+        @context.environments.first['page']['lang'] = @current_lang
+        site = @context.environments.first['site']
+        site['posts'] = @posts
+
+        if defined? Octopress::Linkblog
+          site['linkposts'] = @links
+          site['articles']  = @articles
+        end
       end
 
       def lang
-        # If lang is a local variable, read it from the context
-        lang = [@lang, @context[@lang]].select{|l| @languages.include?(l)}.first
-        if !lang.nil?
+
+        # Read tag arguments as a string first, if that fails,
+        # Look at the local context, to see if it is a variable
+        #
+        if lang = [@lang, @context[@lang]].select do |l| 
+            @languages.include?(l)
+          end.first
+
           lang.downcase
         end
       end

data/lib/octopress-multilingual/version.rb

@@ -1,5 +1,5 @@
 module Octopress
   module Multilingual
-    VERSION = "0.0.9"
+    VERSION = "0.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octopress-multilingual
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors:
 - Brandon Mathis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-26 00:00:00.000000000 Z
+date: 2015-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: octopress-hooks
@@ -119,6 +119,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/octopress-multilingual.rb
+- lib/octopress-multilingual/hooks.rb
+- lib/octopress-multilingual/jekyll.rb
 - lib/octopress-multilingual/set_lang-tag.rb
 - lib/octopress-multilingual/version.rb
 homepage: https://github.com/octopress/multilingual