From ff7ca76d299ac8e86552ef50bbffc2925fb01e7b Mon Sep 17 00:00:00 2001 From: Merlin Date: Sat, 6 Aug 2011 20:24:56 +0200 Subject: [PATCH 1/2] Corrects a typo. --- hyde/ext/plugins/tagger.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hyde/ext/plugins/tagger.py b/hyde/ext/plugins/tagger.py index 6dc54b9..3e50d62 100644 --- a/hyde/ext/plugins/tagger.py +++ b/hyde/ext/plugins/tagger.py @@ -154,7 +154,7 @@ class TaggerPlugin(Plugin): if not 'template' in config: raise self.template.exception_class( - "No Template sepecified in tagger configuration.") + "No Template specified in tagger configuration.") source = content.node_from_relative_path(config.get('source', '')) target = self.site.config.deploy_root_path.child_folder( config.get('target', 'tags')) From eb787c34feaab544c3109864c16039008e7113b9 Mon Sep 17 00:00:00 2001 From: Merlin Date: Sat, 6 Aug 2011 20:33:43 +0200 Subject: [PATCH 2/2] Extends the starter layout with advanced topics. --- .../starter/content/advanced/grouper.html | 49 +++++++++++++ .../starter/content/advanced/meta.yaml | 3 + .../starter/content/advanced/overview.html | 44 +++++++++++ .../starter/content/advanced/sorter.html | 53 ++++++++++++++ .../starter/content/advanced/tagger.html | 51 +++++++++++++ .../{what-next.html => first-steps.html} | 46 +++++++----- hyde/layouts/starter/content/index.html | 2 + .../starter/content/media/css/style.css | 35 +++++++-- hyde/layouts/starter/content/meta.yaml | 2 + hyde/layouts/starter/layout/base.j2 | 14 +++- hyde/layouts/starter/layout/ga.j2 | 13 ++++ hyde/layouts/starter/layout/macros.j2 | 30 +++++++- hyde/layouts/starter/site.yaml | 73 +++++++++++++++++-- 13 files changed, 384 insertions(+), 31 deletions(-) create mode 100644 hyde/layouts/starter/content/advanced/grouper.html create mode 100644 hyde/layouts/starter/content/advanced/meta.yaml create mode 100644 hyde/layouts/starter/content/advanced/overview.html create mode 100644 hyde/layouts/starter/content/advanced/sorter.html create mode 100644 hyde/layouts/starter/content/advanced/tagger.html rename hyde/layouts/starter/content/{what-next.html => first-steps.html} (51%) create mode 100644 hyde/layouts/starter/content/meta.yaml create mode 100644 hyde/layouts/starter/layout/ga.j2 diff --git a/hyde/layouts/starter/content/advanced/grouper.html b/hyde/layouts/starter/content/advanced/grouper.html new file mode 100644 index 0000000..2aa7309 --- /dev/null +++ b/hyde/layouts/starter/content/advanced/grouper.html @@ -0,0 +1,49 @@ +--- +index: 3 +title_ending: "| Grouping" +tags: + - sort + - group +learning_order: 2 +--- + +Grouping +======== + +Content is very often grouped by theme, size, location or any other +conceivable measure. Groups can be traversed in a few ways in Hyde, and +[sorted](sorter.html) at the same time. Here are two common ways: + +Walking all groups and subgroups +-------------------------------- + +{# Resources are sorted by defining a sorter in the configuration file. #} + +{% for grp, res_walker in site.content.walk_level_groups() %} +*{{ grp.description }}* + +{% for res in res_walker %} + * [{{ res.slug|capitalize|replace("-"," ") }}]({{ res.full_url }}) \ + ({{ res.name }}) +{% endfor %} + +{% endfor %} + +{# The above code layout is not arbitrary. Remember that we're building + a Markdown page so every space or line ending has a purpose. +#} + +Listing only the specific (sub)group +------------------------------------ + +{% for res in site.content.walk_resources_grouped_by_advanced() %} + * [{{ res.slug|capitalize|replace("-"," ") }}]({{ res.full_url }}) \ + ({{ res.name }}) +{% endfor %} + +{# You can also call the top level group "level" to get all resources that + are in the group. Or you can list all resources of the same group in the + current node with "resource.node.walk_resource_grouped_by_advanced()". +#} + +{{ macros.render_bottom_article_nav() }} diff --git a/hyde/layouts/starter/content/advanced/meta.yaml b/hyde/layouts/starter/content/advanced/meta.yaml new file mode 100644 index 0000000..1d8def8 --- /dev/null +++ b/hyde/layouts/starter/content/advanced/meta.yaml @@ -0,0 +1,3 @@ +extends: base.j2 +default_block: content +level: advanced diff --git a/hyde/layouts/starter/content/advanced/overview.html b/hyde/layouts/starter/content/advanced/overview.html new file mode 100644 index 0000000..f5505fe --- /dev/null +++ b/hyde/layouts/starter/content/advanced/overview.html @@ -0,0 +1,44 @@ +--- +index: 1 +title_ending: "| Advanced topics" +tags: + - sort + - group + - tag +learning_order: 4 +--- + +More advanced topics +==================== + +If you have read and understood all basic topics covered in +{% for res in site.content.walk_resources_grouped_by_basic()|reverse %} +[{{ res.slug|capitalize|replace("-"," ") }}]({{ res.full_url }}) +{% endfor %} +then you are ready for some more advanced features. They are explained in +the same way as the basic part, building on the knowledge of the previous, +so it is recommended that you follow them in the listed order. + + +{# List all resources from a group, sort them by index and list their tags. #} + +{% for res in resource.node.walk_resources_sorted_by_learning_order() %} +{{ loop.index }}. \ + [{{ res.slug|capitalize|replace("-"," ") }}]({{ res.full_url }}) \ + {% if res.name == "overview.html" %}*(this file)*{% endif %} \ +{# + Sometimes you'll have to add HTML tags to a Markdown file for styling + or adding some special features, and Markdown is OK with that. +#} +tags: +{% for tag in res.meta.tags %} +{# + After wring the tag name, check if that is the last tag in the list. If + it is, don't append the comma at the end. +#} +{{ tag }}{% if tag != res.meta.tags[-1] %},{% endif %} +{% endfor %} + +{% endfor %} + +{{ macros.render_bottom_article_nav() }} diff --git a/hyde/layouts/starter/content/advanced/sorter.html b/hyde/layouts/starter/content/advanced/sorter.html new file mode 100644 index 0000000..557645f --- /dev/null +++ b/hyde/layouts/starter/content/advanced/sorter.html @@ -0,0 +1,53 @@ +--- +index: 2 +title_ending: "| Sorting" +tags: + - sort +learning_order: 1 +--- + +Sorting +======= + +There will come a time when you will need to list and sort resources. Hyde +allows you to walk the site tree and sort the resources by the predefined +settings in your configuration file. + +You can list and sort by name all your content files. + +{# With every sorter defined in the configuration file, nodes get a method + to call. Notice that in the first and last example the method is called + on the whole content of the site, while the second example shows how to + invoke it only on one specific node (in this case the current one). + + Also, some new Jinja filters were used to style the output. +#} +{% for res in site.content.walk_resources_sorted_by_name() %} + * [{{ res.slug|capitalize|replace("-"," ") }}]({{ res.full_url }}) \ + ({{ res.name }}) +{% endfor %} + +Or list only those in the current node (folder). In this case that would be +all advanced topics. + +{# Have in mind that using the next example in a content page (like here) or + using it in a layout (Jinja template that is extended or include by + content pages) will yield very different results. + + In this case it will be called only once, for this resource, and shown + only on this page. If it was in a layout, it would be called for EVERY + resource that uses that layout. In that case the context would be + different, the parent node of the resource could be different and the + results will probably be different too. +#} +{% for res in resource.node.walk_resources_sorted_by_index() %} + {{ loop.index }}. [{{ res.slug|capitalize }}]({{ res.full_url }}) +{% endfor %} + +Or sort files by type and then by size. + +{% for res in site.content.walk_resources_sorted_by_file_type() %} + * [{{ res.source_file.kind|upper }}] {{ res.name }} +{% endfor %} + +{{ macros.render_bottom_article_nav() }} diff --git a/hyde/layouts/starter/content/advanced/tagger.html b/hyde/layouts/starter/content/advanced/tagger.html new file mode 100644 index 0000000..8bb6d9d --- /dev/null +++ b/hyde/layouts/starter/content/advanced/tagger.html @@ -0,0 +1,51 @@ +--- +index: 4 +title_ending: "| Tagging" +tags: + - sort + - tag +learning_order: 3 +--- + +Tagging +======= + +It seems that human beings want to tag everything. You can do it with +Hyde also. In this example **tags** are used to represent technologies +used to build a particular advanced page. So you can see that the +**sorting** was needed for all advanced topics, but **grouping** was +used only for overview and grouping pages. + +Listing by tags +--------------- + +{# You can grab the list of all tags ... #} +{% for tag, meta in site.tagger.tags %} +*{{ tag }}* + +{# ... and get all resurces tagged with that node. #} +{% for res in resource.node.walk_resources_tagged_with(tag) %} + * [{{ res.slug|capitalize|replace("-"," ") }}]({{ res.full_url }}) \ + ({{ res.name }}) +{% endfor %} + +{% endfor %} + +{# Another way to walk through resources tagged with a specific tag is + to use a method that contains that tag's name. + +{% for res in resource.node.walk_resources_tagged_with_sort() %} +{% endfor %} +#} + +Tag combination +--------------- + +You can also search for combination of tags. If you search for a +resource that has **sort**, **tag** and **group** tags, only an +{% for res in resource.node.walk_resources_tagged_with('sort+tag+group') -%} +[{{ res.slug }}]({{ res.full_url }}) +{%- endfor %} +will be returned. + +{{ macros.render_bottom_article_nav() }} diff --git a/hyde/layouts/starter/content/what-next.html b/hyde/layouts/starter/content/first-steps.html similarity index 51% rename from hyde/layouts/starter/content/what-next.html rename to hyde/layouts/starter/content/first-steps.html index aa872ca..fa363d2 100644 --- a/hyde/layouts/starter/content/what-next.html +++ b/hyde/layouts/starter/content/first-steps.html @@ -1,6 +1,6 @@ --- extends: base.j2 -title_ending: "| What next" +title_ending: "| First steps" --- {# In-file metadata. Supplements data from the site's configuration file and node (folder) level data in "meta.yaml" files. @@ -11,8 +11,8 @@ title_ending: "| What next" #} {% block content %} -There and back again -==================== +Walk this way if you're a beginner +================================== This template was created to look at its code. So you should spend about 5% of your time looking at the web from the outside and the other 95% @@ -29,24 +29,24 @@ previous one. ---------------------------------------- The site is made of two folders and a [Hyde configuration][hyde_config] -file. The folders are _content_ and _layout_. +file. The folders are **content** and **layout**. -_content_ contains all your page content, blog articles, pictures and +**content** contains all your page content, blog articles, pictures and resources like CSS and JavaScript. Everything that is unique is here. -_layout_ contains templates and macros. Everything that you'll want to +**layout** contains templates and macros. Everything that you'll want to reuse is here. 2. Jinja2 template ------------------ -_base.j2_ is a very short and simple Jinja2 template. This way you can +**base.j2** is a very short and simple Jinja2 template. This way you can concentrate on some of the basic features. Notice meta and context variables invocation inside curly braces, dynamic media path generation and running all content through the Markdown filter. -_macros.j2_ contains a macro for generating the main menu. +**macros.j2** contains macros for common and repetitive tasks. For more information or to try something new, visit the extensive [Jinja2 documentation][jinja2_docs]. @@ -55,19 +55,31 @@ documentation][jinja2_docs]. 3. Content ---------- -Look at the three files in this order: _index.html_, _what-next.html_ -and _about.html_. +Look at the three files in this order: [index.html](index.html), +[first-steps.html](first-steps.html) and [about.html](about.html). -_Index_ extends the base layout in the classic Jinja way and fills the -content block with some simple Markdown data. +[Index](index.html) extends the base layout in the classic Jinja way and +fills the content block with some simple Markdown data. -_What next_ goes a step furher. It introduces the in-file metadata that -plugins will use to extend and fill the layout. It also uses some new -Markdown features. +[First steps](first-steps.html) goes a step furher. It introduces the +in-file metadata that plugins will use to extend and fill the layout. It +also uses some new Markdown features. -_About_ has a _default_block_ metadata and mixes Markdown content with -Jinja templates. +[About](about.html) has a **default_block** metadata and mixes Markdown +content with Jinja templates. [hyde_config]: http://hyde.github.com/config.html "Hyde configuration" [jinja2_docs]: http://jinja.pocoo.org/docs/templates/ "Jinja2 documentation" + + +4. Advanced sections +-------------------- + +While searching and navigating this template you'll find more files and +sections than mentioned on this page (something like **meta.yaml** +files, the **content/advanced** folder or other Jinja templates). They +are files needed for the [advanced topics](advanced/overview.html) so +just ignore them at the beginning. They will start to make sense while +you're working through the template or will be explicitly explained when +the right time comes. {% endblock %} diff --git a/hyde/layouts/starter/content/index.html b/hyde/layouts/starter/content/index.html index 5b885d6..db35e9e 100644 --- a/hyde/layouts/starter/content/index.html +++ b/hyde/layouts/starter/content/index.html @@ -18,4 +18,6 @@ technologies step by step. Those are: * Jinja templates * Markdown * basic metadata and plugins + +Are you ready for your [first steps](first-steps.html)? {% endblock %} diff --git a/hyde/layouts/starter/content/media/css/style.css b/hyde/layouts/starter/content/media/css/style.css index 407f339..5a6345b 100644 --- a/hyde/layouts/starter/content/media/css/style.css +++ b/hyde/layouts/starter/content/media/css/style.css @@ -4,7 +4,7 @@ } html, body { - color: #fafafa; + color: #ddd; background-color: black; } @@ -20,6 +20,10 @@ body { font-family: Tahoma, sans-serif; } +strong { + color: white; +} + a { color: #f1ee00; } @@ -28,11 +32,11 @@ a:hover, a:focus { text-decoration: none; } -p, ul { +p, ul, ol { margin-bottom: 1.6em; } -ul { +ul, ol { margin-left: 2em; } @@ -49,6 +53,7 @@ header h1 { font-size: 50px; font-weight: normal; text-shadow: -1px 2px 1px black; + color: white; } header h1 span { @@ -60,13 +65,14 @@ header h2 { font-weight: normal; letter-spacing: 11px; text-shadow: -1px 2px 1px black; + color: white; } nav { position: absolute; top: 340px; right: 120px; - width: 200px; + width: 250px; text-align: right; font-family: Anton, Tahoma, sans-serif; } @@ -74,7 +80,7 @@ nav { nav a, nav a:visited { text-decoration: none; - color: #fafafa; + color: white; text-transform: uppercase; font-size: 2.8em; } @@ -121,6 +127,7 @@ nav, aside { font-family: Anton, Tahoma, sans-serif; text-transform: uppercase; margin-bottom: 0.8em; + color: white; } #content h2 { @@ -128,6 +135,8 @@ nav, aside { font-size: 1.2em; font-family: Tahoma, sans-serif; margin-bottom: 1.33em; + color: white; + border-bottom: 1px dashed #888; } #content code { @@ -142,3 +151,19 @@ nav, aside { border-bottom: 1px solid #222; border-left: 1px solid #111; } + +#content .tags { + font-size: 0.8em; + color: #888; +} + +#content .bottom_article_nav { + border-top: 1px dashed #888; + overflow: hidden; + margin-top: 40px; + padding-top: 10px; +} + +#content .bottom_article_nav .next { + float: right; +} diff --git a/hyde/layouts/starter/content/meta.yaml b/hyde/layouts/starter/content/meta.yaml new file mode 100644 index 0000000..e4c1de0 --- /dev/null +++ b/hyde/layouts/starter/content/meta.yaml @@ -0,0 +1,2 @@ +level: basic + diff --git a/hyde/layouts/starter/layout/base.j2 b/hyde/layouts/starter/layout/base.j2 index 69287e3..9c79ef8 100644 --- a/hyde/layouts/starter/layout/base.j2 +++ b/hyde/layouts/starter/layout/base.j2 @@ -22,8 +22,8 @@ way it can be used to generate the list many times, in a footer, etc. #} - {% from "macros.j2" import render_main_menu with context %} - {{ render_main_menu() }} + {% import "macros.j2" as macros with context %} + {{ macros.render_main_menu() }}
{# Main content block. Notice it has to pass through the @@ -38,5 +38,15 @@

Created by {{ author.name}} for {{ project.name }}

+ + {# Some parts of the web are not needed for development and can + wait for production (ex. analytics). They can be included in + the final production build. Create a new config file, extend + the original one and override the "mode" property; then build + the site with the new "production configuration". + #} + {% if site.config.mode == "production" -%} + {% include "ga.j2" %} + {%- endif %} diff --git a/hyde/layouts/starter/layout/ga.j2 b/hyde/layouts/starter/layout/ga.j2 new file mode 100644 index 0000000..a588c73 --- /dev/null +++ b/hyde/layouts/starter/layout/ga.j2 @@ -0,0 +1,13 @@ + diff --git a/hyde/layouts/starter/layout/macros.j2 b/hyde/layouts/starter/layout/macros.j2 index fd08153..b0fea44 100644 --- a/hyde/layouts/starter/layout/macros.j2 +++ b/hyde/layouts/starter/layout/macros.j2 @@ -1,7 +1,35 @@ {% macro render_main_menu() -%} + +{# Set menu item selected if the current resource matches the item in the + site's config file or set "Advanced topics" selected for any resources + that have the "advanced" folder as their parent. +#} {%- endmacro %} + + +{# Advanced topics macro. Renders navigation at the end of the article. #} + +{% macro render_bottom_article_nav() %} +
+{% if resource.next_by_index is not none -%} + +{%- endif %} + +{% if resource.prev_by_index is not none -%} + +{%- endif %} +
+{% endmacro %} diff --git a/hyde/layouts/starter/site.yaml b/hyde/layouts/starter/site.yaml index 3a62801..ef03c8b 100644 --- a/hyde/layouts/starter/site.yaml +++ b/hyde/layouts/starter/site.yaml @@ -1,11 +1,14 @@ mode: learning media_root: media -media_url: media # will use relative path, prepend "/" for absolute path +media_url: /media template: hyde.ext.templates.jinja.Jinja2Template plugins: - hyde.ext.plugins.meta.MetaPlugin - hyde.ext.plugins.auto_extend.AutoExtendPlugin - - hyde.ext.plugins.syntext.SyntextPlugin + # Plugins needed for the advances section. + - hyde.ext.plugins.sorter.SorterPlugin + - hyde.ext.plugins.grouper.GrouperPlugin + - hyde.ext.plugins.tagger.TaggerPlugin context: data: author: @@ -20,8 +23,66 @@ context: install: "http://hyde.github.com/install.html" menu: - title: Home - url: index.html - - title: What next - url: what-next.html + url: /index.html + - title: First steps + url: /first-steps.html + - title: Advanced topics + url: /advanced/overview.html - title: About - url: about.html + url: /about.html + +### Advanced part ### + +# This defines meta data on the whole site. +meta: + # 'nodemeta' will tell Hyde what file to look for inside a folder from + # which to apply meta data to all files (resources) inside it. This is + # a great way of simply adding or modifying properties of a very large + # number of files. + nodemeta: meta.yaml + ga_tracking_code: XX-XXXXXXXX-X + +sorter: + name: # the name of the sorter (no pun intended) + attr: name # by which attributes will resources be sorted + filters: + source_file.kind: html + # You can include only files from a certain folder. + #resource.node: (name of the folder) + #reverse: True # if you need the list backwards + file_type: + attr: + - source_file.kind + - source_file.size + index: + attr: meta.index + filters: + source_file.kind: html + learning_order: + attr: meta.learning_order + filters: + source_file.kind: html + +grouper: + level: + sorter: name + description: Difficulty levels + groups: + - name: basic + description: Basic + - name: advanced + description: Advanced + # You can have more than one group section, depending on your needs. + # For example: "categories", "menu sections", etc. + #category: + # description: To which category a blog post belongs to. + # groups: + # - name: software + # description: Software engineering + # - name: web + # description: Web technologies + # - name: seo + # description: Search Engine Optimization + +tagger: + sorter: name