diff --git a/Gemfile b/Gemfile index 4bb53ed..8877a79 100644 --- a/Gemfile +++ b/Gemfile @@ -7,3 +7,4 @@ gem 'wdm', '~> 0.1', platforms: [:mswin, :mingw] gem 'redcarpet' gem 'middleman-syntax' gem 'rake' +gem 'webrick' diff --git a/Gemfile.lock b/Gemfile.lock index d4994ae..8078e4a 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -102,6 +102,7 @@ GEM thread_safe (~> 0.1) uglifier (3.2.0) execjs (>= 0.3.0, < 3) + webrick (1.7.0) PLATFORMS ruby @@ -114,6 +115,7 @@ DEPENDENCIES redcarpet tzinfo-data wdm (~> 0.1) + webrick BUNDLED WITH - 2.1.4 + 2.2.3 diff --git a/README.md b/README.md index 40f40ef..a51917d 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,97 @@ The documentation for Plume, available at [docs.joinplu.me](https://docs.joinplu.me). -Uses middleman. +Uses [middleman][]. + +## Prerequisites + +* Ruby +* [Crowdin CLI][] v3 if you build translations +* Netlify CLI if you deploy + +## Setting up + +Install RubyGems including [middleman][]: + +```shell +bundle config set --local path vendor/bundle +bundle install +``` + +## Editing documentation + +Run + +```shell +bundle exec middleman +``` + +, visit http://localhost:4567/, and then you can see documentation site. + +Edit files under `source` directory and reload your browser, then you see updated content. But this site doesn't include translations. If you want to include translated pages, see next section. + +After editing, create a pull request. + +## Building site with translation integration + +If you want to build site with translations, you need set up [Crowdin CLI][]. + +Run + +```shell +bundle exec rake build_site +``` + +and then the site with translations is built under `build` directory. You can see the site using one-liner server such as + +```shell +ruby -run -e httpd build +``` + +or web server such as Caddy. + +## Updating translation strings + +When you add and/or modify strings from current sources, you may want to translate them. To do so, updated contents need to be uploaded to Crowdin. Run + +```shell +bundle exec rake crowdin:upload +``` + +then you can translate strings at Crowdin. + +## Building translation site + +When you build site for https://translate.docs.joinplu.me/, run + +```shell +bundle exec rake build_trans +``` + +then the site is built under `translate` directory. + +## Deploying site + +You need [Netlify CLI][] if you deploy site. + +Run + +```shel +bundle exec rake deploy +``` + +then you can see updated site at https://docs.joinplu.me/. + +## Deploying translation site + +Run + +```shell +bundle exec rake deploy_trans +``` + +and then you can see updated translation site at https://translate.docs.joinplu.me/. + +[middleman]: https://middlemanapp.com/ +[Crowdin CLI]: https://support.crowdin.com/cli-tool/ +[Netlify CLI]: https://cli.netlify.com/ diff --git a/Rakefile b/Rakefile index 8546ab6..7cac224 100644 --- a/Rakefile +++ b/Rakefile @@ -32,12 +32,12 @@ task :build_site => [:build_base, "crowdin:download"] do end task :build_base do - sh "middleman", "build" + sh "bundle", "exec", "middleman", "build" end desc "Build site for translate.docs.joinplu.me" task :build_trans => "crowdin:download" do - sh "middleman", "build", "--build-dir", TRANS_DIR + sh "bundle", "exec", "middleman", "build", "--build-dir", TRANS_DIR (LOCALE_DIR/PSEUDO_LANG/"trans").glob("**/*.html").each do |html| doc = html.read @@ -49,7 +49,7 @@ task :build_trans => "crowdin:download" do end task :build_trans_src do - sh "middleman", "build", "--build-dir", LOCALE_DIR + sh "bundle", "exec", "middleman", "build", "--build-dir", LOCALE_DIR end desc "Deploy docs.joinplue.me" diff --git a/config.rb b/config.rb index 8cf5f7c..153811b 100644 --- a/config.rb +++ b/config.rb @@ -1,6 +1,8 @@ # Activate and configure extensions # https://middlemanapp.com/advanced/configuration/#configuring-extensions +set :relative_links, true + set :markdown_engine, :redcarpet set :markdown, :fenced_code_blocks => true, :smartypants => true, :with_toc_data => true @@ -20,3 +22,19 @@ configure :build do # activate :minify_css # activate :minify_javascript end + +DEFAULT_LANGUAGE = "en" + +helpers do + def link_to_lang(name, code, **opts) + base = code == DEFAULT_LANGUAGE ? "/" : "/#{code}/" + path = base + current_page.path + .sub(/index\.html\z/, "") + .sub(%r|\.html\z|, "/") + link_to(h(name), path, hreflang: h(code), rel: "alternate") + end +end + +def URI.escape(*args) + encode_www_form_component(*args) +end diff --git a/source/_nav.erb b/source/_nav.erb index 57dbf3e..5b74d7d 100644 --- a/source/_nav.erb +++ b/source/_nav.erb @@ -1,10 +1,10 @@