Editing Files (HTML, Scss, Javascript and Assets)

Finding Your Source Files

With project based sites all your source files (HTML, Scss, Javascript and Assets) can be found at ./prjects/PROJECTNAME/src. These files are copied from the parent /src directory when you run the create-project command and therefore you are free to edit and maintain them as you please.

With non-project based sites you need to edit the /src files directly which makes upgrading very tricky so again our recommmended approach is using project based sites created with the gulp create-project command.

With the power of gulp watch any changes made to your files are automatically loaded, gulp tasks are rerun and Browser Sync will update the changes in your browser.

All /src files and processd by Gulp into the /dist directory by default.

HTML Files + Twig

As of AppStrap Docs 4.x you can now use the powerful Twig template engine to build your HTML files and then Gulp will process them into raw HTML in your /dist directory.

Twig is a powerful and flexible templating engine that allows you to dynamically generate HTML pages based on variables, control structures, and reusable blocks. Here are a few key examples of how we use Twig in AppStrap Docs:

Variables and Conditional Logic:

Our config settings are automatically passed to Twig as variables which you can then use in your templates and use them to dynamically change content. For example, in the body tag:

<body {% if bodyClass %} class="{{bodyClass}}" {% endif %}>

Here, bodyClass is a variable passed from the page front matter. If it exists, Twig outputs the class attribute with the value of bodyClass. If the variable is not set, no class attribute is added.

Includes:

Twig allows you to reuse code by including other templates. This helps keep your code clean and modular. For example:

{% include '@partials/head.html' %}

This line includes the content of head.html from the /src/html/@partials folder, allowing you to reuse the head section across multiple pages.

Blocks and Embeds:

Blocks and embeds are powerful features in Twig that enable inheritance and reusable content. Here, Twig uses embed to extend a partial template and add additional content:

{% embed '@partials/header.html' %}
  {% block navbarBrandContent %}
    <a href="#" class="navbar-text fs-5 align-self-stretch">Contact Us</a>
  {% endblock %}
{% endembed %}

The embed tag imports header.html from /src/html/@partials and allows you to override or add content inside it using block. In this case, the navbarBrandContent block is overridden with custom content.

NOTE: Using Twig is totally optional, you can of course just write raw HTML in your /src/html/*.html files and it will work just fine too.

SASS Files

By default when you create a project Gulp will copy over the following files and then reference to the parent /src directory so you can use the AppStrap Docs core Scss files without needing to maintain them:

/src/scss/_custom.maps.scss - thia allows you to alter the utility maps set by Bootstrap and AppStrap Docs, see https://getbootstrap.com/docs/5.3/utilities/api/#using-the-api for more information.

/src/scss/_custom.style.scss - this file can house any custom SASS code you want to automatically add to AppStrap Docs and is loaded and the end of the SASS build so you can override anything needed.

/src/scss/_custom.variables.scss - this file allows you to alter variables set by Bootstrap and AppStrap Docs, see overriding colours as an example.

/src/scss/theme.style.scss - this is the parent SASS for AppStrap Docs, in most cases you won’t need to alter this but if you want to exclude any SASS partials and build more custom on a project this is where you’d do it.

Config options To override which SASS files are included in Gulp builds you can use the config paths.src.scssFiles: [] & paths.src.scssFilesWatched: [] options and to output the compiled CSS to somewhere else you can use paths.dist.cssDir but this is only recommended for advanced users.

If you prefer to just write plain CSS you can create static CSS files and include them in your pages with the additionalCSS config setting:

additionalCSS: [ // add additional CSS files to <head>
  './projects/myproject/css/custom2.css'
  './projects/myproject/css/custom2.css'
],

Javascript Files

The /assets/src/js/custom.script.js allows you to override plugin functions within AppStrap Docs as well as add your own plugin definitions using AppStrap Docs to load in the theme assets.

You can also use the AppStrap Docs Javascript API to react to javascript events in AppStrap Docs:

themePreload: Before any AppStrap Docs Javascript has run
themePrePlugins: Before any AppStrap Docs Javascript has run
themeLoaded: After the theme has loaded everything
themePluginsExtras: Add new plugin integrations or override existing ones.

Config options

You can alter the Javascript files compiled by AppStrap Docs using the paths.src.JSSourceFiles file glob. The order is important but you can for example exclude a given plugin using '!./src/js/plugins/fakeLoader.js' in the glob. Similarly with paths.src.JSSourceFilesVendors which compiles the vendor packages needed for AppStrap Docs.

When the config setting includeCustomJS: true is set /dist/assets/js/custom.script.js is automatically included in HTML files. You can also add additional Javascript files to your pages using additionalJS for example:

  additionalJS: [ // add additional JS files to footer
    './projects/myproject/js/custom1.js',
    './projects/myproject/js/custom2.js'
  ],

Assets

All files within /src/assets are automatically copied to /dist/assets by Gulp when you run yarn gulp or yarn gulp build OR whenever you edit or add new files.

Gulp will also create a file called assets-map.json within /dist/assets which lists all the assets used per page so you can keep track of your file assets. In addition, when you run yarn gulp build the assets-map.json file used to remove any files from /dist/assets that are not currently in use within your HTML files.

Config options To disable the removal of unused assets you can set buildSettings.unusedAssets: false in your config.PROJECT.js file.

yarn gulp build will also compress your image files to make them as small as possible when copied to /dist/assets, this step can take awhile if you have a lot of images so it’s only run on the build command.

To reference assets in your HTML simply use /assets/img/FOLDER/FILE.EXTENSION.

Next Steps

Now you should have an overview of all the file assets you need to work with so you can follow our how tos and examples section for building more with AppStrap Docs

Quickstart