Expert starter

It is a blank directory to make a copy of and start a new project with. It includes the required JS and CSS files from TheDocs as well as icon fonts, PHP files and some images.

The expert starter has several features which is not included in the basic starter. Those features give you more freedom in customizing your template and writing extra codes. It includes a gulpfile with necessary tasks to start a web server, watch files for changes and compile SCSS and JS files. Finally, you can run a command to have all the required files for production copied to a directory.

How to get started?

Follow the below steps to create a project directory with all the required plugins and tools installed.

Step 1

Make a copy of expert/ directory to your desire workspace.

Step 2
  1. Download and install Node.js if it's not installed on your machine
  2. Install the Gulp command line tools, gulp-cli, with npm install gulp-cli -g
  3. Navigate to the root directory of your project and run npm install to install dependencies
  4. Run gulp serve.

With the above command, a static web server starts in your browser which points to /src directory. It watch your files to reload the browser upon change to the HTML files, or JS and CSS files. Also, it watch your SCSS and JS files to compile them to page.min.css and page.min.js upon each change.

Step 3

Now it's time to configure your website.

  • Script: Open /assets/js/src/config.js and change the desire values.
  • Style: Open /assets/scss/_theme.scss and change the SCSS variables.
Step 4

Time for development. Now you're ready to create your HTML files and writing your custom CSS and JS codes.

- HTML
Since most of the websites have a global layout for whole of the application, you might want to start modifying one of the layout templates and create a global layout for your website.

- SCSS
Write your additional styles inside /assets/scss/_style.scss. Feel free to create more scss files and even subdirectories inside /scss folder to split your code to smaller chunks and import them inside /scss/page.scss file. Our Gulp task is watching all of the scss files inside /scss directory and recompile the page.min.css upon each change.

- JavaScript
Your additional JavaScript codes should be write inside /assets/js/src/script.js. Again, if you need to split your code to several JS files, simply create them inside /js/src directory and require them inside the /js/src/page.js. Our Gulp task is watching all of the JS files inside /js/src directory and recompile page.min.js after each change using Webpack.

Step 5

Done with development? Run gulp dist to deploy your code inside /dist directory. This task simply remove unnecessary files (scss files, scss folder, unminified css and js files, etc.) in the /dist folder. Now you can use the /dist folder in your server side coding or upload to your web server.

What is the available gulp tasks?

Our Gulpfile includes the following commands and tasks:

Task Description
gulp serve Running a server and start watching for change on html, scss and js files to compile and reload the browser
gulp dist Create a /dist folder, compile scss and js files, and copy all the project's files inside the /dist directory except unnecessary ones
gulp img Uses the imagemin plugin to minify the images inside /assets/img directory

How to update to a new version?

Usually, you only need to update the following files and directories in assets/ folder for minor updates. If any extra changes were required, we'll write it in the changelog. For major releases (i.e. from 2.x to 3.x), you probably need to update your HTML code as well.

  • /fonts
  • /php
  • /plugin/thedocs

Sometimes, you might need to update some parts of the following files if we state it in the changelog description. We do our best to reduce these changes.

  • /scss/_theme.scss
  • /scss/_page.scss
  • /js/src/config.js
  • /js/src/page.js

Please note that after updating the above files and directories, you need to run gulp dist to recompile the page.min.css and page.min.js once again and upload them to your server.

How to add a 3rd-party plugin?

If the plugin has CDN and you're willing to use it, simply include the plugin into your HTML pages by adding css and js files of the plugin from CDN. If you want to host the plugin on your own server, put the plugin inside /assets/plugin and import it into your HTML pages.

To configure and initialize the plugin, write the required JS code inside /assets/js/src/script.js file with the help of the plugin's documentation.

How to remove some vendors to decrease CSS and JS files size?

Please take a look at /assets/js/src/page.js and /assets/scss/page.scss files. Both of them have a Vendors section which is responsible for importing vendors' assets. Simply comment the import line that you'd like to remove the vendor from final CSS or JS file.