Wrangler.py

ラングラー

Wrangler は、ブログを構築していない人向けの静的サイト ジェネレーターです。

特徴：

• コンテンツを YAML、JSON、または Markdown で記述します
• 素晴らしい Jinja2 ライブラリを使用してテンプレートを構築します。 Twig を知っていればすぐに馴染みます。
• 本当に速いです (相対的なものですが、200 ページ、88 個のテンプレートが 4 秒以内に完了します)。
• スマート キャッシュにより、変更したページのみが再レンダリングされます。
• シンプルな CLI により、数秒で起動して実行できます。
• 内蔵の基本的なHTTPサーバーとファイル監視
• カスタムフィルター、拡張機能、フック、パーサーで拡張可能

Springload では、静的サイトを作成する必要があることがよくありますが、それを実行できるツールを見つけるのに苦労しました。ラングラーに乗り込みます。コンテンツが一連のブログ投稿としてフォーマットされることは想定されていません。静的アセットをコピーしたり、SaSS を処理したり、コーヒーを淹れたりすることはありません。

それは 1 つのことを実行し、その 1 つのことを非常にうまく実行します。

気に入っていただければ幸いです。

クイックスタート

pip 経由で Wrangler をインストールします。

 pip install wrangler

現在のディレクトリに新しいプロジェクトを生成します.

 wrangler create .

これにより、多数のディレクトリが作成されます。動作を確認するには、小さな自動生成サイトを構築します。

 wrangler build content www

選択したエンジン、またはhttp://127.0.0.1:8000/にある便利な組み込みサーバーを介してサイトを提供します。

 wrangler serve www

コンテンツとテンプレートの変更を監視し、自動的に再構築したいですか?そのためのアプリがあります。 watch タスクは、 buildと同じオプションをすべて受け取ります。

 wrangler watch content www

さて、それはうまくいきました、さあどうしますか？

Wrangler のファイル構造

Wrangler は非常に単純なファイルシステム規則に従っています。

my-site/
| --content
| ----index.yaml
| --lib
| --templates
| ----template.j2
| --var
| --wrangler.yaml
| --www

• content - コンテンツディレクトリ。サイト構造はこのディレクトリを反映します。 content/index.yamlがある場合は、 www/index.htmlを取得します。
• templates - jinja2 .j2テンプレートが存在する場所
• www - Web ルート フォルダー。実際、どこにでも出力できます。私たちは、賢明なデフォルトとして www を選択しただけです。
• lib - カスタム拡張機能、クラス、フックなどがここに入ります。いくつかの Python モジュールを作成し、結果を Wrangler に返します。
• var - テンプレート キャッシュとファイル オブジェクト キャッシュを保持します (Wrangler はすぐに使える Pickle と Shelve のコンボを使用します)

これらのパスはすべてwrangler.yamlで変更できます。

コンテンツの操作

Wrangler は、ユーザーが何らかの構造化データを操作しており、それらのデータ ファイルを HTML (必要に応じて従来の ASP) に変換することを想定しています。

パッケージには、json、yaml、markdown (yaml フロントマターを含む) の 3 つのパーサーが含まれています。これらはファイルごとに動作するため、これは完全に有効です。

my-site/
| --content
| ----index.yaml
| ----page-2.json
| ----page-3.md

YAML (.yml、.yaml)

 meta :
    title : My title
    template : template.j2
    description : " My cool page! "
data :
    content : " Here's some page content! "
    blocks :
        - " Lots of content "
        - " even more content "
        - " wow, so much content! " 

JSON (.js、.json)

{
    "meta" : {
        "title" : " My title " ,
        "template" : " template.j2 " ,
        "description" : " My cool page! "
    },
    "data" : {
        "content" : " Here's some page content! " ,
        "blocks" : [
            " Lots of content " ,
            " even more content " ,
            " wow, so much content! "
        ]
    }
}

マークダウン (.md、.markdown)

 ---
title : My title
template : template.j2
description : " Markdown uses yaml front-matter "
---
# A heading!
Some paragraph text

## Another heading! 
Even more text

---
Nice HR you got there.

* A list
* with some
* list items

これは素晴らしいマークダウンチートシートです

メタデータのオプション

ページに関連するあらゆるものにメタデータを使用します。ここには好きなものを入力できますが、いくつかの予約語があります。

 meta :
    title : " Musings on the pronounciation of doge "
    alias : " Doge "
    template : " template.j2 "
    class : DogePage
    hide_from_nav : true
    description : " Is it dog-e, doog, douge, douche? How do I properly refer to this meme? "
    keywords : ["much", "analytics", "such", "SEO"]
    output_file_extension : asp
    weight : 1
    thumbnail : /assets/images/thumb/doge-100x100.jpg
    related :
        - content/other-page.yaml
        - content/pages/this-page-here.yaml 

タイトル

ナビゲーション内のページ名 (おそらくタイトルタグも)

テンプレート

テンプレート パス (wrangler.yaml のtemplates_dirに相対)

エイリアス

タイトルの短縮形。代わりにナビゲーションで使用できます。

クラス

ページ オブジェクトの Python クラスを置換しようとします。 wrangler.Core.Pageのサブクラスである必要があります

ナビゲーションから隠す

このページをナビゲーション ツリーから非表示にします。

説明

缶に書いてあること

キーワード

キーワードのリスト

出力ファイルの拡張子

wrangler.yaml のデフォルトのoutput_file_extensionをオーバーライドします。ページはこの拡張機能を使用してレンダリングされます。

重さ

ページを下位から上位に並べるのに便利です。デフォルトでは、Wrangler はファイルシステムのアルファベット順の並べ替えを使用します。

サムネイル

サムネイル画像へのパス

関連している

関連ページの一覧です。これにより、テンプレートで、他のページに関する基本情報 (タイトルや説明など) を取得できるようになります。

生成されたメタデータ

ラングラーは、アクセスできるテンプレート内でメタデータにいくつかの内容を自動的に追加します。

{{ meta.url }}
{{ meta.segments }}
{{ meta.filepath }}
{{ meta.mtime }}

{{ meta.children }}
{{ meta.parents }}
{{ meta.parents_siblings }}

URL

ビルドされたファイルへのパスoutput_dirを基準とした相対パス) (例: /

セグメント

すべての URL セグメントのリスト: ["sub-directory", "index.html"]

ファイルパス

入力ファイルの名前

分時間

変更された時刻。これを使用して、たとえばブログのタイムスタンプを作成できます。

子供たち

現在のディレクトリの直接の子

両親

現在のファイルと/間のすべてのノード

両親_兄弟

親ディレクトリの兄弟。

ページデータ

ページ データは完全にオプションです。

この小さなページ、 custom-page.yamlを見てみましょう。必要に応じて、データのないページを Wrangler にスローして、テンプレートcustom-page.j2内のすべてをハードコードすることができます。

 meta :
    title : No content!
    template : custom-page.j2
    output_file_extension : txt

これにより、 www/custom-page.txtが構築されます。

データへのアクセス

Wrangler には jinja2 マークダウン フィルターが付属しています。マークダウン ファイルを使用している場合、マークダウンはdata.contentで入手できます。コンテンツをマークダウン フィルターにパイプすれば完了です。

< div class = " content " >
    {{ data.content|markdown }}
</ div >

Markdown は素晴らしい記述形式ですが、より構造化されたデータを扱う場合にはいくつかの制限が生じる可能性があります。 YAML ファイルと JSON ファイルの場合は、 dataディクショナリの一部にアクセスし、必要に応じてそれらを接続します。

< div class = " content " >
{{ data.content }}
{% for block in data . blocks %}
    < p >{{ block }}</ p >
{% endfor %}
</ div >

---

構成

Wrangler の編集可能なオプションは、プロジェクト ルートのwrangler.yamlファイルに保存されます。

開いてみると、 wrangler 、 site 、 extensions 3 つのノードが見つかります。

ラングラー

これはコア構成、つまりハードコアなものです。それは次のようになります。

 wrangler : 

    # Template directory relative to your project root
    templates_dir : templates

    # Default template to load if no template is specified for a page
    default_template : template.j2

    # Default output file extension. Note this can be overwritten in the content
    # by specifying 'output_file_extension' in the 'meta' area
    output_file_extension : html

    # Supported data formats. Ensure a parser is registered for each type.
    # More information about parsers can be found in the link at the top of the file.
    data_formats : ['yaml', 'yml', 'json', 'js', 'md', 'markdown']

    # Ignore hidden files, and files starting with underscores
    ignore : ['.','_']

    # Prints all the internal plumbing output to stdout
    verbose : false

    # Always force all pages to be rendered
    force : false

    # Run without the cache (useful for developing custom page classes, to prevent them
    # from being cached each run).
    nocache : false

    # The location of the template cache zip file. 
    # Ensure the var path exists and is writeable by the user
    build_cache_file : var/build.cache
    compiled_templates_file : var/jinja
    compiled_templates_log : var/jinja.log

    # Custom methods/classes go in the lib directory, for instance
    # lib/Page.py or lib/Extensions.py or lib/Filters.py
    lib_path : lib

# file continues.... 

拡張子

ここで設定した拡張機能を設定します。拡張機能を使用すると、必要な Python 関数を実行し、その結果をテンプレートに挿入できます。

 # wrangler.yaml continued...
extensions :
    # Sitemap generates a tree structure of your entire site, relative to the
    # webroot specified here 
    # 
    #   {{ extensions.sitemap }}
    # 
    # We leave it up to you to iterate over the sitemap and print everything in
    # a pretty manner, but this gist might get you started:
    # https://gist.github.com/joshbarr/111

    sitemap : 
        webroot : / 

{{ extensions.cachebuster }}

いくつかのデフォルト拡張子が含まれています: sitemap 、 fileinfo 、およびcachebuster

サイト

サイト変数はサイト全体の変数であり、 siteオブジェクトの子としてテンプレート内で使用できます。

たとえば、画像のパスを取得するには、 {{ site.paths.images }}を呼び出すことで、入力の手間を省くことができます。

 # wrangler.yaml continued...
site :
    paths : 
        css : assets/css
        js : assets/js
        assets : assets 

 {# Hey, it's those handy vars I set in my site_vars #}
{{ site.paths.css }}

このドキュメントはすべてwrangler.yamlファイルにも含まれているため、迷うことはありません。

---

コマンドラインオプション

ラングラー作成

単一の位置引数、つまり新しいプロジェクトを作成するパスを受け取ります。

 cd my-sweet-site && wrangler create .

# or 
wrangler create my-sweet-site

ラングラービルド

input_dir入力ディレクトリ ( site/contentなど) output_dir出力ディレクトリ ( wwwなど)

wrangler build content www

コンテンツが最後に変更された時期に関係なく、レンダリングを強制します。

wrangler build content www --force

すべてのページオブジェクトを再キャッシュします

wrangler build content www --nocache

すべてのページの出力ファイル拡張子をクラシックaspに変更します (なぜそんなことをする人がいるでしょうか?)

 wrangler build content www -o ".asp"

input_dir内で検索するデータ形式をjsonに変更

 wrangler build content www -d 'json'

テンプレートディレクトリの場所を変更する

 wrangler build content www -t other-templates-dir

設定ファイルの場所を変更する

 wrangler build content www -c site/config/wrangler.yaml

ラングラー時計

wrangler buildと同じオプションがすべてあります

ファイルが変更されるたびにすべての配管を出力します。

wrangler watch content www --verbose

ラングラーサーブ

1 つの位置引数 (提供するディレクトリ) とオプションの--port (デフォルト 8000) を受け入れます。

wrangler serve www --port 8001

ラングラークリーン

「var」ディレクトリからテンプレート キャッシュとオブジェクト キャッシュを削除します。

wrangler clean

---

ボンネットの下で

Wrangler は起動時に、プロジェクトのlibディレクトリにあるすべての Python モジュールを読み込みます。

これにより、コア関数を拡張してページ データを操作できるようになります。たとえば、データベースからいくつかの値をロードして、テンプレートで使用できるようにすることができます。

内部構造

build呼び出すと、Wrangler はcontent/ディレクトリにツリー構造の表現を構築します。

これは、ノードを処理するための便利なコンテナであるNodeGraphにマッシュされるNodeオブジェクトの二重リンク リストを使用しています。

 # Pseudocode
NodeGraph :
    # The nodes in their hierarchical structure, eg:
    tree :        
        Node :
            children :
                - Node :
                    children :
                        - Node
                - Node :
                    children :
                        - Node
                        - Node
                        - Node
   
    # The 'all' dictionary is the same nodes represented in a flat structure.
    # This can be much quicker to iterate over than the tree, and you can
    # access both from within your hooks and extensions.
    # The filepath is used as the unique key.
    all :
        
        content/index.md :
            Node :
                # node's data...

        content/other-page.md :
            Node :
                # node's data...

ノードは、その子だけでなくその親にもアクセスできます。

 # More pseudocode
Node :
    path : " content/index.md "
    children :
        - Node :
        - Node :
        - Node :
    parent :
        Node :

整理整頓のため、Node オブジェクトはページ データの表現を直接保持しません。ノードは単なるコンテナです。

この説明のアイデアに従って、ノードには実際のページ クラスを保持するカーゴプロパティがあります。

 from wrangler . Core import Node

class GoldBullion ( object ):
    price = 1200

the_node = Node ( "index" , "content/index.md" , parent = None , cargo = None )

the_node . add_cargo ( GoldBullion ())

cargo = the_node . get_cargo ()

print cargo . price 

ページクラス

ページはソース ファイルのデータのdict表現を保持し、 Rendererデータにアクセスするための一貫した方法を提供します。カスタム ページを作成するには、 wrangler.Core.Pageサブクラス化するだけで、自動的に読み込まれます。

便利なヒント:カスタム クラスの名前がPageの場合、すべてのページのデフォルトのPageオブジェクトが上書きされます。

 # lib/Page.py
import wrangler . Core as wrangler

class Page ( wrangler . Page ):
    def get_content ( self ):
        return self . data [ "data" ]

    def get_metadata ( self ):
        return self . data [ "meta" ]

    def get_properties ( self ):
        print "Hey, I'm a custom page instance!"
        return {
            "title" : self . get_title (),
            "alias" : self . get_short_title (),
            "description" : self . get_meta_description (),
            "url" : self . get_tidy_url (),
            "show_in_navigation" : self . show_in_navigation (),
            "weight" : self . get_weight (),
            "thumbnail" : self . get_thumbnail ()
        }

上記の例では、3 つのメイン ページ メソッドget_content() 、 get_metadata() 、およびget_properties()を変更しています。

get_content()

ページがレンダリングされるときに呼び出され、これはテンプレートでdataオブジェクトとして使用できます。

<!doctype html>
    < div class = ' dump-of-data-object ' >
        {{ data.content }}
    </ div >

get_metadata()

ページがレンダリングされるときに呼び出されます。これはmetaオブジェクトです。

<!doctype html>
    < title >{{ meta.title }}

get_properties()

説明するのが少し難しくなりますが、それでも素晴らしいです。 Nodeがレンダリングされると、子、兄弟、親、手動で関連するページなど、現在のページに関連するページに関する特定の情報が要求されます。

すべてを他のすべてと共有するのではなく、各Pageクラスは他のページと共有してもよい基本情報を記述します。

    def get_properties ( self ):
        return {
            "title" : self . get_title (),
            "alias" : self . get_short_title (),
            "url" : self . get_tidy_url (),
            "show_in_navigation" : self . show_in_navigation (),
            "weight" : self . get_weight (),
            
            # Let's add the modified time, so our theoretical parent
            # page could know when we last saved the file. 
            "mtime" : self . getmtime ()
        }

カスタムページクラス

非常に単純な例、ページ上のすべてのテキストを反転するカスタム ページ クラスを見てみましょう。とても実用的です。

まず、ページ メタにclassプロパティを設定して、Wrangler にどのクラスをロードするかを指示します。

コンテンツ/カスタム.md:

 ---
class : RightToLeft
---
# My custom page

With its custom content.

次に、 lib/ディレクトリ内のどこかに、 Pageサブクラス化する新しいクラスを作成します。 lib/ディレクトリ内のどこに配置されるかは問題ではありません。唯一のルールは、 Pageオブジェクトをサブクラス化する必要があるということです。

lib/pages.py

 import wrangler . Core as wrangler

class RightToLeft ( wrangler . Page )
    def get_content ( self ):
        for key , val in self . data [ "data" ]:
            self . data [ "data" ][ key ] = val [:: - 1 ]
        return self . data [ "data" ]

素晴らしい！私たちのページは右から左へのテキストで印刷されます。

コンテンツパーサー

wrangler.yamlファイルを見ると、 ["yaml", "json", "md"]の 3 つのファイル タイプを受け入れていることがわかります。

Wrangler にはデフォルトで 3 つのパーサー ( Yaml 、 Markdown 、およびJsonが含まれており、これらは入力ファイルを使用して意味のあるデータとして表します。

自分で巻く

オートローダーは、 wrangler.Core.Parserサブクラス化するものを探します。

たとえば、テキスト形式をサポートするには、 lib/Parsers.pyのどこかでこれを行うことができます。

 from wrangler . Core import Parser
from lxml import objectify
from collections import defaultdict

class XmlParser ( Parser ):
    accepts = [ "xml" , "robotlanguage" ]

    def interpret ( self , file_contents ):
        return root = objectify . fromstring ( file_contents )

フックとエクステンション

Wrangler は、フックとエクステンションの処理にウインカーの信号を使用します。

フック

フックは、レンダリング プロセスの重要なポイントで発生するシグナルです。これらはモジュールに表示される順序で処理され、受信オブジェクトを直接変更できます。また、Wrangler のconfig 、 renderer 、 reporterにもアクセスできます。

 from wrangler . Core import before_render , after_render , load_item , save_item , render_item

@ before_render
def before ( ** kw ):
    nodes = kw [ 'nodes' ]
    config = kw [ 'config' ]
    renderer = kw [ 'renderer' ]
    reporter = kw [ 'reporter' ]
    print "Hey, I'm a hook!"
    return "foo!"

@ after_render
def after ( ** kw ):
    nodes = kw [ 'nodes' ]
    config = kw [ 'config' ]
    renderer = kw [ 'renderer' ]
    reporter = kw [ 'reporter' ]
    print "Hey, I'm a hook!"
    return ""

拡張機能

拡張機能は、テンプレートのextensions辞書に便利なデータを返す Python スクリプトです。

この小さなスクリプトを見てみましょう。

 # lib/my_extensions.py
from wrangler . Core import extension

@ extension
def my_extension ( sender , ** kwargs ):
    # Add some config to your YAML file and access it here: 
    config = kwargs [ 'config' ][ 'extensions' ][ 'my_extension' ]
    return config [ "string_to_print" ]

extensions.YOUR_EXTENSION_NAMEのテンプレートからアクセスできます。

< em class = " extension " >
  {{ extensions.my_extension }}
</ em >

その結果、次の出力が得られます。

 < i > "This is my basic extension!" </ i > 

拡張機能の構成

wrangler.yamlには、拡張機能を管理するためのセクションがあります。

    # My extension just prints a string... not very exciting!
    my_extension :
        string_to_print : " This is my basic extension! " 

フィルター

Wrangler を使用すると、カスタム フィルターを使用して Jinja2 を拡張できます。

フィルターは、lib ディレクトリーlib/内の任意のファイルに入れる必要があります。これらは、 template_filterという適切な名前のデコレーターを介して接続されます。

 #lib/filters.py
from wrangler . Core import template_filter
from jinja2 import contextfilter

@ template_filter
def my_filter ( value ):
    return value . lower ()

jinja のcontextfilterまたはenvcontextfilterにアクセスする必要がある場合は、それらをインポートして関数に適用することもできます。

jinja2 のコンテキスト フィルターについて詳しく読む

 #lib/filters.py
from wrangler . Core import template_filter
from jinja2 import contextfilter

@ template_filter
@ contextfilter
def my_filter ( context , value ):
    print context
    return value