KDE.org/Neverland: Difference between revisions

From KDE Community Wiki
No edit summary
m (→‎Supported Tags: Add 'lang="text"' to syntaxhighlight tag)
 
(5 intermediate revisions by one other user not shown)
Line 9: Line 9:
=== Requirement ===
=== Requirement ===
* Git
* Git
* NodeJs >= 6.0
* NodeJs >= 5.2
* Basic understanding of [[Mustache|http://mustache.github.io/mustache.5.html]]
* Basic understanding of [http://mustache.github.io/mustache.5.html Mustache]


=== Installing Neverland ===
=== Installing Neverland ===
Line 17: Line 17:
<code>git clone git://anongit.kde.org/websites/neverland.git</code>
<code>git clone git://anongit.kde.org/websites/neverland.git</code>


Cd to the <code>neverland</code> folder:
Change to the <code>neverland</code> folder:


<code>cd neverland</code>
<code>cd neverland</code>
Line 36: Line 36:


<code>node neverland watch --theme neverland</code>
<code>node neverland watch --theme neverland</code>
== Usage ==  
== Usage ==  
To create a new theme, you can run:
To create a new theme, you can run:
Line 99: Line 100:
</syntaxhighlight>                                                                                                         
</syntaxhighlight>                                                                                                         
There are some key points here:
There are some key points here:
* Those tags using [[BEM|https://en.bem.info/]] methodology
* Those tags using [https://en.bem.info/ BEM] methodology
* {{& }} is the same as {{{ }}} because Neverland uses [[this library|https://github.com/janl/mustache.js]]
* <code><nowiki>{{& }}</nowiki></code> is the same as <code>{{{ }}}</code> because Neverland uses [https://github.com/janl/mustache.js this library]
* You should define both which part should be transform and default part
* You should define both which part should be transform and default part


You can check for full tags in [[#Supported Tags]] section
You can check for full tags in [[#Supported Tags]] section


Finally, you can output your theme to wordpress/mediawiki theme by running:
Finally, you can output your theme to ''wordpress/mediawiki/drupal'' themes by running:


<code>node neverland build --theme your-theme-name</code>
<code>node neverland build --theme your-theme-name</code>


Your theme will be placed under <code>buildings</code> directory
Your theme will be placed under <code>buildings/your-theme-name</code> directory


== Commands ==
== Commands ==
Line 135: Line 137:


== Supported Tags ==
== Supported Tags ==
<syntaxhighlight>
<syntaxhighlight lang="text">
article__link
article__link
article__title
article__title
Line 152: Line 154:
navbar__category--end
navbar__category--end
</syntaxhighlight>
</syntaxhighlight>
== Write a builder for other platforms ==
== Write a builder for other platforms ==
<small>will be updated</small>
=== Requirements ===
Basically Neverland doesn't restrict the way you write your builder. But there are still some requirement you must have to follow:
 
* There must be a <code>build.js</code> file under <code>workers/platform</code> directory
* You have to add your platform manually by adding it to <code>platforms</code> array on <code>architect/commands/build.js</code> line 25.
 
=== How the default builders work ===
You can refer the default builders. Here is how they work:
 
* First, platform templates are prepared under <code>workers/platform/templates</code>. These templates content some tags such as <code>{{{ header }}}</code>, <code>{{{ body }}}</code>, <code>{{{ footer }}}</code> ...
* Neverland copy all files from <code>workers/platform/templates</code> to <code>buildings/theme-name/platform</code>
* Neverland renders <code>{{{ body }}}</code>,<code>{{{ footer }}}</code> … with the corresponding files <code>body.mustache</code>,<code>footer.mustache</code> in <code>blueprints/theme-name</code> folder
* After that, it renders the asset parts.
* Finally, it renders <code>{{{article__author}}}</code>, <code>{{{article__author--link}}}</code> tags with the platform tags
 
 
Take a look at the wordpress builder (workers/wordpress/build.js), and you can see those basic steps.

Latest revision as of 13:16, 26 October 2020

Introduction

KDE's Neverland is able to build full themes from a set of template files. The designer needs to only care about the css/js files and the correct nesting of the layout (html). Once satisfied, complete themes for any supported CMS can be outputted and then used accordingly. The project is based on node.js.

Installation

Requirement

  • Git
  • NodeJs >= 5.2
  • Basic understanding of Mustache

Installing Neverland

Clone the repository:

git clone git://anongit.kde.org/websites/neverland.git

Change to the neverland folder:

cd neverland

Switch to gsoc branch:

git checkout gsoc

Install dependencies:

npm install

Install gulp globally:

npm install gulp -g

You can check if everything is ok by running:

node neverland watch --theme neverland

Usage

To create a new theme, you can run: node neverland new your-theme-name

Your new theme will appear under blueprints directory

To start building a theme, you can run:

node neverland watch --theme your-theme-name

or

gulp watch --theme your-theme-name

Currently you should keep your theme structure by default

Now you can code your theme normally.

To convert your html theme to wordpress or mediawiki theme, you need some additional works. Every theme shares some same parts such as Navigation bar, Category links, Sidebar. In order to let Neverland understand where to transform these parts to corresponding cms part you need to some default Mustache tags.

For example:

You have your navbar like this:

<ul class="header__categories">                                                                                                                              
    <li class="header__categories--item">                                                                
            <a href="#" class="header__categories--link">Work</a>                                            
    </li>                                                                                                     
    <li class="header__categories--item">                                                                
            <a href="#" class="header__categories--link">Portfolio</a>                                       
    </li>                                                                                                     
    <li class="header__categories--item">                                                                
            <a href="#" class="header__categories--link">About</a>                                           
    </li>                                                                                                                                                                                      
</ul>

You should insert the tags like this:

<ul class="header__categories">                                                                               
{{#navbar__category}}                                                                                         
{{&navbar__category}}                                                                                         
    <li class="header__categories--item">                                                                
        <a href="{{&navbar__category--link}}" class="header__categories--link">{{&navbar__category--name}}</a>
    </li>                                                                                                     
{{&navbar__category--end}}                                                                                    
{{/navbar__category}}                                                                                         
{{^navbar__category}}                                                                                         
    <li class="header__categories--item">                                                                
        <a href="#" class="header__categories--link">Work</a>                                            
    </li>                                                                                                     
    <li class="header__categories--item">                                                                 
        <a href="#" class="header__categories--link">Portfolio</a>                                        
    </li>                                                                                                     
    <li class="header__categories--item">                                                                
        <a href="#" class="header__categories--link">About</a>                                            
    </li>                                                                                                     
{{/navbar__category}}                                                                                         
</ul>

There are some key points here:

  • Those tags using BEM methodology
  • {{& }} is the same as {{{ }}} because Neverland uses this library
  • You should define both which part should be transform and default part


You can check for full tags in #Supported Tags section

Finally, you can output your theme to wordpress/mediawiki/drupal themes by running:

node neverland build --theme your-theme-name

Your theme will be placed under buildings/your-theme-name directory

Commands

node neverland [commands]

new <theme-name> Create new skeleton theme
delete --theme <theme-name> Delete theme
themes List existing theme
sass --theme <theme-name> Compile sass files
watch --theme <theme-name> Using gulp watch
build --theme <theme-name> --platform,-p <platform> Build theme for specific platform. If platform is ommited, Neverland will build for all supported platforms.

Supported Tags

article__link
article__title
article__thumbnail
article__time
article__author--link
article__author--name
article__content
article__category
article__category--end
article__category--link
article__category--name
navbar__category
navbar__category--link
navbar__category--name
navbar__category--end

Write a builder for other platforms

Requirements

Basically Neverland doesn't restrict the way you write your builder. But there are still some requirement you must have to follow:

  • There must be a build.js file under workers/platform directory
  • You have to add your platform manually by adding it to platforms array on architect/commands/build.js line 25.

How the default builders work

You can refer the default builders. Here is how they work:

  • First, platform templates are prepared under workers/platform/templates. These templates content some tags such as {{{ header }}}, {{{ body }}}, {{{ footer }}} ...
  • Neverland copy all files from workers/platform/templates to buildings/theme-name/platform
  • Neverland renders {{{ body }}},{{{ footer }}} … with the corresponding files body.mustache,footer.mustache in blueprints/theme-name folder
  • After that, it renders the asset parts.
  • Finally, it renders {{{article__author}}}, {{{article__author--link}}} tags with the platform tags


Take a look at the wordpress builder (workers/wordpress/build.js), and you can see those basic steps.