cleanup, docs, etc.
This commit is contained in:
parent
ab671c2782
commit
743e917733
GPG key ID:
F1F29650D537C773
8 changed files with 174 additions and 23 deletions
133
README.md
133
README.md
|
|
@ -16,15 +16,138 @@ Make sure you have node installed on your machine. The best way to manage node i
|
|||
|
||||
### Site Content
|
||||
|
||||
You will need to create a site folder in `/projects/sites/<site-name>` (ignored by `git`), add the basic site config to it, and have some sort of content in order for the site to generate. Before previewing the site, run `npm run set-current -w=sites --site=<site-name>` so that the site is linked to the frontend. See [Architecture](#architecture) for more information.
|
||||
You will need to create a site folder in `/projects/sites/<site-name>` (ignored by `git`), create a `config.json` file to define how the site generates pages, and have some sort of content in order for the site to generate. Before previewing the site, run `npm run set-current -w=sites --site=<site-name>` so that the site is linked to the frontend.
|
||||
|
||||
#### `config.json`
|
||||
|
||||
Without this file properly set up, your site will not function. There are a few key fields to define here. Consider the following example:
|
||||
|
||||
```json
|
||||
{
|
||||
"routes": {
|
||||
"/": {
|
||||
"template": "markdown",
|
||||
"content": "/content/home.md",
|
||||
"stylesheetUrls": [
|
||||
"/content/home.css"
|
||||
],
|
||||
"id": "home",
|
||||
"fullTitle": "Home | My Site",
|
||||
"title": "Home"
|
||||
},
|
||||
"/about": {
|
||||
"template": "markdown",
|
||||
"content": "/content/about.md",
|
||||
"stylesheetUrls": [
|
||||
"/content/about.css"
|
||||
],
|
||||
"id": "about",
|
||||
"fullTitle": "About | My Site",
|
||||
"title": "About"
|
||||
},
|
||||
"/gallery": {
|
||||
"template": "gallery-list",
|
||||
"config": "/content/gallery.json",
|
||||
"stylesheetUrls": [
|
||||
"/content/gallery.css"
|
||||
],
|
||||
"id": "gallery",
|
||||
"title": "Gallery",
|
||||
"fullTitle": "Gallery | My Site",
|
||||
"view": {
|
||||
"title": "$ENTRY",
|
||||
"fullTitle": "$ENTRY | Gallery | My Site",
|
||||
"stylesheetUrls": [
|
||||
"/content/gallery.css"
|
||||
]
|
||||
},
|
||||
}
|
||||
},
|
||||
"header": [
|
||||
{
|
||||
"path": "/",
|
||||
"displayName": "Home"
|
||||
},
|
||||
{
|
||||
"displayName": "Galleries",
|
||||
"children": [
|
||||
{
|
||||
"displayName": "Anthro",
|
||||
"path": "/anthro"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"path": "/about",
|
||||
"displayName": "About"
|
||||
},
|
||||
{
|
||||
"path": "https://example.org",
|
||||
"displayName": "Home Site",
|
||||
"target": "_blank"
|
||||
}
|
||||
],
|
||||
"id": "my.example.org",
|
||||
"stylesheetUrls": [
|
||||
"/content/base.css"
|
||||
],
|
||||
"tags": "/content/tags.json",
|
||||
"themes": {
|
||||
"dark": {
|
||||
"displayName": "Dark",
|
||||
"type": "dark",
|
||||
"url": "/content/dark.css"
|
||||
},
|
||||
"light": {
|
||||
"displayName": "Light",
|
||||
"type": "light",
|
||||
"url": "/content/light.css"
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
##### Routes
|
||||
|
||||
Routes is the most important field here. It defines what HTML pages get generated by the static site generator. It is a key-value object where the key represents the intended URL of the page; this must always start with "/" (a route keyed by just "/" will represent the home page, e.g.`example.org/index.html` otherwise shortened to `example.org`).
|
||||
|
||||
The `template` field determines which view template is used when generating the page. See [templateType.d.ts](/libs/types/src/content/templates/templateType.d.ts) for the full list of currently supported template types. The full config for routes is defined in [routing.d.ts](/libs/types/src/config/routing.d.ts); at minimum, routes follow the `SharedRouteDefinition`. General templates will just generate a main page, while list-related templates like `article-list` and `gallery-list` have a list page (the main config) and a child "view" page (the `view` field in the main config) (e.g. if you have a `gallery-list` at `/gallery`, the main config will be for `/gallery` and the `view` config will be used for `/gallery/view?id={entry}`).
|
||||
|
||||
Depending on the template type, there may be `config` and/or `content` fields. Both of these are remote files that are fetched when the page first starts to load. `content` is used typically by generic templates that directly load some sort of `content`; `markdown` templates, for example, directly pull text from a markdown file, so when `"template": "markdown"`, `"content": "/content/path/to/markdown.md"`. `config` is used by more complex templates. List templates, for example, define a list of `entries`. In order to see what config you need, look for the corresponding template type name in [the types folder for templates](/libs/types/src/content/templates). Parsing these can be complex, so separate guides will be available for creating those templates.
|
||||
|
||||
The `id` of the page is used for identifying the page in code for caching purposes. `title` is a display-name for the route used in breadcrumb navigation/etc. `fullTitle` is the display-name for the page in the browser tab. `stylesheetUrls` is an array of strings linking to stylesheets that will be appended to the page. These are appended when navigating to the page and removed when navigating away from it.
|
||||
|
||||
`scriptUrl` allows loading an optional script file containing callbacks that are executed based on page events; these must be defined at the end of your script file in order to be used like so:
|
||||
|
||||
```js
|
||||
export const callbacks = {
|
||||
onPageClosed,
|
||||
onPageLoaded,
|
||||
}
|
||||
```
|
||||
|
||||
All callbacks are optional. `onPageClosed` is called when the user is leaving the page they are currently on, which is useful if you have made some sort of modification to the page that may unintentionally be transferred to the next. `onPageLoaded` is called when the current page route loads; each view template emits a `loaded` event when it is finished loading its config and executing any tasks related to loading the template. Note that this doesn't necessarily mean asyncronous data will be loaded into view when this executes, simply that the main view is marked `ready` and will have the main template structure in place.
|
||||
|
||||
##### Other Fields
|
||||
|
||||
`id` is used for identifying the site in browser cookies. This is important to allow for remembering certain things like if the user wanted to permanently hide gallery warnings or if the user picked a certain site theme.
|
||||
|
||||
`header` is an array of objects which define entries for site navigation. If you want to directly link a page, set the `path` of the page to the relative url of the page. You can optionally set `target` to set the `<a>` tag's `target` (e.g. opening in a new tab instead of same tab with `_blank`). If you want to add a drop-down of links, set `children` instead of `path`; `children` is recursive, in that it is an array of the same shape of objects found directly in `header`, which can either be links or a nested drop-down. Whether you're adding a drop-down of links or a direct link, remember to set `displayName` to set the link's text.
|
||||
|
||||
`stylesheetUrls` is the same as the `stylesheetUrls` found in the routes described above, with the exception that the root config.json `stylesheetUrls` are loaded/shared for every single page. `themes` is a special collection of stylesheets - it is a key-value object where the key is the id of the theme. `displayName` is what is displayed in the theme picker dropdown to the user; `type` describes what type of theme it is so that the frontend can default to a theme respecting the user's browser/system theme (see [themes.d.ts](/libs/types/src/config/themes.d.ts) for supported types); `url` is of course the url to the CSS file itself.
|
||||
|
||||
`tags` is used for definining filters based on tags assigned to entries in list-related templates. `tags` can either be a link to a JSON file or directly be embedded. In either case, it is an array of objects with the following fields: `displayName` (what the user sees on the list page's filters panel); `category` (optional, used for dividing related tags in the filters panel; uncategorized tags will appear at the top of the filters panel, and categorized tags will appear in subheadings); and finally `tagId` (identifies the tag used by list entries).
|
||||
|
||||
#### Other Site Content
|
||||
|
||||
You are free to structure your site's content however you want, so long as `config.json` is directly in the root of the main site folder, and so long as it is understood that all files in this folder are assumed to be located at `/content/**` on the web-host. For example, if you have a site in the `/projects/sites/sites` folder named `my.example.org`, this `my.example.org` becomes `https://my.example.org/content` when the site is built and pushed to the host, assuming you are using the default setup used by the development/build scripts described in the ReadMe. `/projects/sites/sites/my.example.org/stylesheets` becomes `https://my.example.org/content/stylesheets`, `/projects/sites/sites/my.example.org/galleries/my-gallery.json` becomes `https://my.example.org/content/galleries/my-gallery.json`, and so on.
|
||||
|
||||
### Live Preview
|
||||
|
||||
You can run `npm start -w=frontend` in the terminal to spin up a server. Open the address shown the terminal in your browser to preview what your site looks like. It has hot reloading, which means you can make changes to site code and certain files that will be instantly reflected on the page you have open. Some more core files may cause the page to fully reload, while some simple changes like stylesheet/component changes may be reflected without full reloading. Note that fetched content (page markdown/config files) is not caught by hot reload, so you will need to reload manually in those cases.
|
||||
You can run `npm start` in the terminal to spin up a server. Open the address shown the terminal in your browser to preview what your site looks like. It has hot reloading, which means you can make changes to site code and certain files that will be instantly reflected on the page you have open. Some more core files may cause the page to fully reload, while some simple changes like stylesheet/component changes may be reflected without full reloading. Note that fetched content (page markdown/config files) is not caught by hot reload, so you will need to reload manually in those cases.
|
||||
|
||||
### Building
|
||||
|
||||
TBA
|
||||
Running `npm run build` will build out the project. Be sure that you had previously set `npm run set-current -w=sites --site=<site-name>` before building so that the site builder can build from config.json. When the build command is executed, `vite-ssg` will build the frontend into the `/projects/frontend/dist` folder. The build process will ensure that the previously set site is copied into the generated `dist` directory. The `dist` directory contains your static site's files.
|
||||
|
||||
## Background
|
||||
|
||||
|
|
@ -53,7 +176,7 @@ This repo is set up to be a monorepo to help manage different projects under the
|
|||
|
||||
### /projects/frontend
|
||||
|
||||
TBA
|
||||
The frontend is the main project which builds your website from your content config. The frontend is designed to work with dynamic content, i.e. it will not bake your content directly into the resulting HTML so that you can manage content separately. The types of pages that are generated are defined by page templates and are implemented by views (`/projects/frontend/src/views`).
|
||||
|
||||
### /projects/sites
|
||||
|
||||
|
|
@ -63,8 +186,6 @@ This package helps manage multiple websites in one place. The `./sites` folder i
|
|||
|
||||
Note that some hosts, such as [surge.sh](https://surge.sh), do not allow for management of individual files and instead require that all files be pushed in one go. In that case, make sure the `/content` folder is present when the `/projects/frontend` project is built before syncing, and sync content changes with the `/projects/frontend` build instead.
|
||||
|
||||
TBA: ensure build command has option to include or exclude `/content` when building or provide separate build commands
|
||||
|
||||
### /projects/cms
|
||||
|
||||
In order to manage larger galleries, Mackenzii has a pre-configured [Strapi](https://docs.strapi.io/) package that can be used locally in combination with the scripts under the `sites` project which will pull data from Strapi into a format usable by Mackenzii. Note that this configured Strapi is _not_ meant to be hosted on a production server. If you do, make sure you do not commit any environment secrets to git (they should be gitignored) and read the docs on how to host Strapi. You will also want to point the bridge scripts to the hosted version instead of local, or consider repurposing them into a middleware server and have your Mackenzii point to the appropriate URLs instead of `/content/**`.
|
||||
|
|
|
|||
4
libs/types/src/config/routing.d.ts
vendored
4
libs/types/src/config/routing.d.ts
vendored
|
|
@ -44,6 +44,8 @@ export type MarkdownDefinition = ContentfulRouteDefintion & {
|
|||
export type ArticleListDefinition = ConfigfulRouteDefinition & {
|
||||
template: 'article-list'
|
||||
view: {
|
||||
title: string
|
||||
fullTitle: string
|
||||
stylesheetUrls: string[]
|
||||
}
|
||||
}
|
||||
|
|
@ -54,6 +56,8 @@ export type ArticleListDefinition = ConfigfulRouteDefinition & {
|
|||
export type GalleryListDefinition = ConfigfulRouteDefinition & {
|
||||
template: 'gallery-list'
|
||||
view: {
|
||||
title: string
|
||||
fullTitle: string
|
||||
stylesheetUrls: string[]
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
"type": "module",
|
||||
"scripts": {
|
||||
"start": "vite",
|
||||
"build": "vue-tsc && vite-ssg build",
|
||||
"build": "vue-tsc && vite-ssg build && node post-build.js",
|
||||
"preview": "vite preview"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
|
|
|||
10
projects/frontend/post-build.js
Normal file
10
projects/frontend/post-build.js
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
import { existsSync } from 'fs';
|
||||
import { readFile } from 'fs/promises';
|
||||
import { setCurrent } from '../sites/src/set-current.js'
|
||||
|
||||
(async () => {
|
||||
if (existsSync('../sites/sites/current.txt')) {
|
||||
const site = await readFile('../sites/sites/current.txt', { encoding: 'utf-8' });
|
||||
setCurrent(site);
|
||||
}
|
||||
})();
|
||||
|
|
@ -22,6 +22,10 @@ type DisplayedEntries = { [key: string]: {
|
|||
hiddenByTags?: boolean
|
||||
}}
|
||||
|
||||
const emits = defineEmits<{
|
||||
(e: 'loaded'): void
|
||||
}>()
|
||||
|
||||
const ready = ref(false)
|
||||
const currentRoute = getCurrentRoute()
|
||||
const routeStore = useRouteStore()
|
||||
|
|
@ -88,6 +92,7 @@ onMounted(async () => {
|
|||
document.title = routeConfig.fullTitle
|
||||
ready.value = true
|
||||
hasWarnings.value = !!(await Promise.all(Object.values(list.entries))).find(other => !!other.warnings)
|
||||
emits('loaded')
|
||||
})
|
||||
</script>
|
||||
|
||||
|
|
|
|||
|
|
@ -130,6 +130,7 @@ const mapStrapiResponseToMackenzii = async (inVal) => {
|
|||
};
|
||||
|
||||
(async () => {
|
||||
console.log('NOTE: This is currently only built to support gallery lists. Article lists and other content are not supported');
|
||||
const rl = readlinePromises.createInterface(process.stdin, process.stdout);
|
||||
let fetchUrl = '';
|
||||
try {
|
||||
|
|
|
|||
|
|
@ -1,17 +1,3 @@
|
|||
import symlinkDir from 'symlink-dir';
|
||||
import { existsSync } from 'fs';
|
||||
import { mkdir } from 'fs/promises';
|
||||
import { setCurrent } from '../src/set-current.js';
|
||||
|
||||
(async () => {
|
||||
const site = process.env.npm_config_site;
|
||||
if (!!site) {
|
||||
await symlinkDir(`sites/${site}`, '../frontend/content');
|
||||
if (!existsSync('../frontend/dist')) {
|
||||
await mkdir('../frontend/dist');
|
||||
}
|
||||
await symlinkDir(`sites/${site}`, '../frontend/dist/content');
|
||||
console.log('done');
|
||||
} else {
|
||||
console.error('Parameter "site" was not provided!');
|
||||
}
|
||||
})();
|
||||
setCurrent(process.env.npm_config_site);
|
||||
|
|
|
|||
24
projects/sites/src/set-current.js
Normal file
24
projects/sites/src/set-current.js
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
import symlinkDir from 'symlink-dir';
|
||||
import { existsSync } from 'fs';
|
||||
import { mkdir, unlink, writeFile } from 'fs/promises';
|
||||
|
||||
export const setCurrent = async (site, ctx) => {
|
||||
const managerPath = ctx?.managerPath || '../sites';
|
||||
const frontendPath = ctx?.frontendPath || '../frontend';
|
||||
if (!!site) {
|
||||
await symlinkDir(`${managerPath}/sites/${site}`, `${frontendPath}/content`);
|
||||
if (!existsSync(`${frontendPath}/dist`)) {
|
||||
await mkdir(`${frontendPath}/dist`);
|
||||
}
|
||||
await symlinkDir(`${managerPath}/sites/${site}`, `${frontendPath}/dist/content`);
|
||||
|
||||
if (existsSync(`${managerPath}/sites/current.txt`)) {
|
||||
await unlink(`${managerPath}/sites/current.txt`);
|
||||
}
|
||||
await writeFile(`${managerPath}/sites/current.txt`, site, { encoding: 'utf-8' });
|
||||
|
||||
console.log('done');
|
||||
} else {
|
||||
console.error('Parameter "site" was not provided!');
|
||||
}
|
||||
};
|
||||
Loading…
Add table
Reference in a new issue