KDE.org/Neverland: Difference between revisions

From KDE Community Wiki
m (→‎Supported Tags: Add 'lang="text"' to syntaxhighlight tag)
 
(8 intermediate revisions by 3 users not shown)
Line 3: Line 3:
== Introduction ==
== Introduction ==


We are currently working on a new design for KDE.org, projectname Neverland. On this page you can read about our research, ideas and progress.
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.


== Getting involved ==
== Installation ==


If you are interested in joining the webteam for the developement of Neverland, please join us at our IRC channel #kde-www. There are a variety of options to get involved. This includes:
=== Requirement ===
* Git
* NodeJs >= 5.2
* Basic understanding of [http://mustache.github.io/mustache.5.html Mustache]


* WordPress
=== Installing Neverland ===
* Usability
Clone the repository:
* Design


<code>git clone git://anongit.kde.org/websites/neverland.git</code>


The needs steadily change, and there is always room for coders who are able to contribute HTML, CSS or PHP.
Change to the <code>neverland</code> folder:


* IRC channel: #kde-www
<code>cd neverland</code>
* Mailinglist: [http://mail.kde.org/mailman/listinfo/kde-www kde-www] See http://kde.org/mailinglists/ for details
* Projectpage: [https://projects.kde.org/projects/websites/neverland Neverland Projectpage]
==Documentation for Neverland==


To be filled.
Switch to <code>gsoc</code> branch:


==Meetings==
<code>git checkout gsoc</code>


To be filled.
Install dependencies:


==The Team==
<code>npm install</code>


{| class="wikitable" border="1"
Install gulp globally:
 
<code>npm install gulp -g</code>
 
You can check if everything is ok by running:
 
<code>node neverland watch --theme neverland</code>
 
== Usage ==
To create a new theme, you can run:
<code>node neverland new your-theme-name</code>
 
Your new theme will appear under <code>blueprints</code> directory
 
To start building a theme, you can run:
 
<code>node neverland watch --theme your-theme-name</code>
 
or
 
<code>gulp watch --theme your-theme-name</code>
 
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.
 
<u>For example:</u>
 
You have your navbar like this:
 
<syntaxhighlight lang="html">
<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>                                                                                                       
</syntaxhighlight>
 
You should insert the tags like this:
<syntaxhighlight lang="html">
<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>
</syntaxhighlight>                                                                                                       
There are some key points here:
* Those tags using [https://en.bem.info/ BEM] methodology
* <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 can check for full tags in [[#Supported Tags]] section
 
Finally, you can output your theme to ''wordpress/mediawiki/drupal'' themes by running:
 
<code>node neverland build --theme your-theme-name</code>
 
Your theme will be placed under <code>buildings/your-theme-name</code> directory
 
== Commands ==
node neverland [commands]
{| class="wikitable"
|-
|-
!width=25%| Name
| new <theme-name>
!width=20%| Nick
| Create new skeleton theme
!width=35%| Skills
! Main task
|-
|-
| Ingo Malchow
| delete --theme <theme-name>
| neverendingo
| Delete theme
| PHP, HTML, CSS, image creation/manipulation
| Adjusting look and feel of KDE sites
|-
|-
| Eugene Trounev
| themes
| it-s
| List existing theme
| Design/Layout, CG/Vectors, HTML5, CSS3, JS, Web 3.0
| Design
|-
|-
| Sayak Banerjee
| sass --theme <theme-name>
| sayakb
| Compile sass files
| PHP, Lots of JS, HTML, CSS, Graphics
| Migrating existing websites and designing new ones over Neverland, adding lots of JS love
|-
|-
| Hans Chen
| watch --theme <theme-name>
| Mogger
| Using gulp watch
| Complaining, design
| Testing
|-
|-
| 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 ==
<syntaxhighlight lang="text">
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
</syntaxhighlight>
== 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 <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.