Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/chrisnajman/one-page-site-template

One-page site template with multiple elements, including accordion, carousel, modal and slide-in.
https://github.com/chrisnajman/one-page-site-template

accessibility babel-es6 html-css-javascript postcss scss webpack

Last synced: 10 days ago
JSON representation

One-page site template with multiple elements, including accordion, carousel, modal and slide-in.

Host: GitHub
URL: https://github.com/chrisnajman/one-page-site-template
Owner: chrisnajman
License: mit
Created: 2023-05-04T06:20:13.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-10-19T14:40:13.000Z (3 months ago)
Last Synced: 2024-11-21T00:52:28.417Z (2 months ago)
Topics: accessibility, babel-es6, html-css-javascript, postcss, scss, webpack
Language: HTML
Homepage: https://chrisnajman.github.io/one-page-site-template/
Size: 2.03 MB
Stars: 0
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

---
permalink: /index.html
---

[Website (Git Pages)](https://chrisnajman.github.io/one-page-site-template)

# One-page Webpack Site Template with SASS, Babel and PostCSS

**Important**: It is assumed that you have `node.js` installed on your computer.

## webpack.config.js and package.json

### webpack.config.js

Note that by default, the path to the production folder will be set as `dist`:

- `path: path.resolve(__dirname, "dist"),`.

However, the output folder has been changed to `docs` (which makes publishing to Git Pages much simpler):

- `path: path.resolve(__dirname, "docs"),`.

Also,

`
devServer: {
static: ["./dist"],
},

has been changed to:

`
devServer: {
static: ["./docs"],
},
`
### package.json

Similarly, all references in this file to `./dist` have been changed to `./docs`.

## Description

This repository can be used to build a simple one-page website (i.e not React or equivalent). If you use it you can be sure that:

1. Modern Javascript will work on older browsers,
2. `.scss` files compile to CSS (usingthe new Dart SASS implementation which allows files to be imported with `@use` and `@forward`, replacing the now deprecated `@import`), and
3. the compiled CSS will work on older browsers,
4. You will also be able to easily publish the page to Git Pages.

- Item 1 is taken care of by Babel,
- Item 2 is taken care of by SASS,
- Item 3 is taken care of by PostCSS.
- Item 4, see: 'Publishing to Git Pages' and `Publishing to Git Pages from /dist folder', below.

## Folder structure

- All development is done inside `src` folder:
- - `src/index.html`
- - `src/js`
- - `src/sass`
- - `src/img`
- Production files are generated to `docs` folder.
- - Output files in `docs` are all on the same level — no folders.
- - - As noted above, the default output folder name, `dist`, has been changed to `docs`.

## Features

- Responsive HTML and images,
- Slide-in `aside` for e.g a glossary,
- Carousel, with option to view slides and captions stacked.
- Accessible accordion,
- Accessible images (scrollbars at predetermined widths),
- Accessible tables (scrollbars when content overflows the browser window),
- Accessible modal pop up (launched from 'Disclaimer' button),
- Styled scrollbars (Firefox and Webkit browsers only).

**Note**: for Sass path to background images see `src/sass/components/_bg-image.scss`.

### SASS

Webpack 5's inbuilt SASS package now supports the `@use` and `@forward` instead of `@import`. However, if you don't want
to use this syntax you could either:

- put all `.scss` in `style.scss` (avoiding importing altogether) or
- use the deprecated `@import`. You will get warnings, but the site won't break.

In Dart Sass, `/` for division is deprecated. Use `math.div()`, together with `@use sass:math` instead. See:

- `sass/components/_testmath.scss` for a usage example.

### Older browsers

I've used `@supports([selector : "value"])` to shield older browsers from modern CSS.

### JavaScript

Two Javascript files are imported into `index.js` using ES6 import modules. If you don't want to use this syntax you can
copy and paste the javascript from the subsidiary `.js` files into `index.js`.

**Important**: `import "../sass/style.scss"` must be at the top of `index.js`.

### JavaScript disabled

If JavaScript is disabled the site still functions well:

- all accordion content displays,
- the slides and captions are stacked,
- the glossary is visible under the main text,
- the modal pop up content is displayed under the main heading (h1).

## Installation

### Clone repository

In a folder on your computer:

- `git clone [email protected]:chrisnajman/dist-test.git` OR
- `git clone [email protected]:chrisnajman/dist-test.git [new name]` (replacing `[new name]` with the folder name of your choice.)

**Note**: if you're going to upload your completed project to a new GitHub repository:

1. Delete the `.git` folder from the root.
2. Initialise the folder with `git init`.
3. Create the new repository on GitHub.
4. In your local folder:
1. `git add .`
2. `git commit -m "First commit"`
3. `git remote add origin [SSH Url]`
4. `git push origin master`
5. For Git Pages see "Publishing to Git Pages", below.

## npm commands

Once installed it is advisable to check if all the packages are up to date by running:

- `npm i -g npm-check-updates`

Then, to update `package.json`, run:

- `ncu --upgrade`

Finally, to install updated packages, run:

- `npm i`

### Build commands

A number of build commands can be found in `package.json` under `"scripts"`. I have found that the most useful one is:

- `npm run cbs`

This does three things:

1. It deletes the current `docs` production folder, then
2. builds it again from the `src` folder, then
3. launches a web server on `http://localhost:8080/`.

Once done, any changes made in `src` will automatically update the web browser.

**Note**: the final production files will be in the `docs` folder.

## Publishing to Git Pages

**Important**: make sure to run e.g. `npm run cbs` before pushing to Github.

- `git push origin master`

Then, on the GitHub repository page, click on the 'Settings' tab. From the 'Settings' page, click on 'Pages' in the left hand menu.

- Under 'Branch' select 'main'.
- Under '/(root)' select '/docs'.
- Click 'Save'.

### Publishing to Git Pages from /dist folder

If you decide to change the output folder back to `dist` (as per default `webpack.config`) then you will have to do the following:

**Important**: make sure to run e.g. `npm run cbs` before pushing to Github.

After running `git push origin master`, run:

- `git subtree push --prefix dist origin gh-pages`

## Credits

- I got most of the setup done by following these tutorials by **Swashbuckling with Code**:
- - [Creating and Understanding a Basic Webpack 5 Setup](https://www.youtube.com/watch?v=X1nxTjVDYdQ&list=PLmZPx_9ZF_sB4orswXdpThGMX9ii2uP7Z&index=1)
- - [Webpack 5 CSS Walkthrough: Sass, PostCSS and more!](https://youtu.be/SH6Y_MQzFVw)
- - - These are part of a playlist: [Webpack 5](https://www.youtube.com/playlist?list=PLmZPx_9ZF_sB4orswXdpThGMX9ii2uP7Z)
- [PNG to WEBP conversion] (https://onlineconvertfree.com/complete/png-webp/)
- [Favicon generator] (https://realfavicongenerator.net/)
- [Accessible modal window using ARIA] (https://van11y.net/accessible-modal/)
- [Accessible accordion by Lyndsey Kopacz] (https://www.a11ywithlindsey.com/blog/javascript-accessibility-accordions)
- - [My tweaks to the accordion, on Codepen] (https://codepen.io/Naj-codepen/pen/rNzgowb)

[Website (Git Pages)](https://chrisnajman.github.io/one-page-site-template)