Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Snickdx/pwadocs
Turn your mkdocs site into a PWA
https://github.com/Snickdx/pwadocs
mkdocs mkdocs-material mkdocs-site pwa service-worker workbox
Last synced: 4 days ago
JSON representation
Turn your mkdocs site into a PWA
- Host: GitHub
- URL: https://github.com/Snickdx/pwadocs
- Owner: Snickdx
- Created: 2017-09-08T20:57:02.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-04-19T03:18:50.000Z (over 1 year ago)
- Last Synced: 2024-07-12T00:28:35.319Z (4 months ago)
- Topics: mkdocs, mkdocs-material, mkdocs-site, pwa, service-worker, workbox
- Language: HTML
- Homepage: https://nmendez.app/pwadocs
- Size: 3.73 MB
- Stars: 22
- Watchers: 3
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome - Snickdx/pwadocs - Turn your mkdocs site into a PWA (HTML)
README
# PWADocs
A PWA wrapper for Mkdocs Material.
This project combines:
* Workbox-cli for building the service worker.
* MkDocs: Static site doc site geneator
* Material for MkDocs: A Material theme for mkdocs
[DEMO](https://nmendez.app/pwadocs)
## Requirements
* Python 2 or 3
* Node. npm
## Installation
Install python dependencies
```
$ pip install -r requirements.txt
```
Install npm packages
```
$ npm install -g workbox-cli
```
## Configuration
### Configuring the site
To set the app's name, description google analytics and title edit the folling directives in the mkdocs.yml file.
```yaml
# Project information
site_name: 'Material for MkDocs'
site_description: 'A Material Design theme for MkDocs'
site_author: 'Martin Donath'
site_url: 'https://squidfunk.github.io/mkdocs-material/'
```
View [mkdocs site](https://www.mkdocs.org/#mkdocs) for more configuration options, customization and adding pages.
### Updating App Icons
You can override the apps default icons by placing images into the following files:
* ./docs/img/favicon.ico
* ./docs/assets/icons/logo-36.png
* ./docs/assets/icons/logo-192.png
* ./docs/assets/icons/logo-512.png
### Configuring The Web Manifiest
Configure additonal logos, set the name of the pwa, theme colors orientation etc by editing the manifest.json file located in ./docs/manifest.json refer to [Google Developer Docs](https://developers.google.com/web/fundamentals/web-app-manifest) for configuration options.
```json
{
"name": "Site Name",
"short_name": "Site name",
"start_url": "index.html",
"display": "fullscreen",
"scope": ".",
"orientation":"portrait",
"icons": [
//...
}
```
## Live Reload Server
Use mkdocs live reload server to view changes during development. The service worker is not used inorder to see site changes.
```
$ mkdocs serve
```
## Updating The Site
Simply edit the markdown files run the build command and redeploy. You may also want to update the version number of your app in mkdocs.yml.
Users who have the app installed would be prompted to update the next time they open it in online mode.
## Build site
Once mkdocs and workbox is installed simply build the site with the following command.
```bash
$ npm run build
```
The complete PWA should be built and located in ./site/
## External Resouces for Customization
1. [Mkdocs Configuration](https://www.mkdocs.org/user-guide/configuration/)
2. [Mkdoc Materil Customization](https://squidfunk.github.io/mkdocs-material/customization/)
3. [Mkdocs Material Extensions](https://squidfunk.github.io/mkdocs-material/extensions/admonition/)
4. [Workbox Manifest Guide](https://developers.google.com/web/tools/workbox/guides/get-started)