Goldenwere/mackenzii
Goldenwere/mackenzii
1
0
Fork 0
Code Activity Actions

begin working on readme

Browse source
This commit is contained in:
lightling 2024-04-13 03:27:42 -04:00
parent 9400f1d665
commit 7f03e9ef13
1 changed files with 40 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
README.md
View file

@ -1,18 +1,47 @@
# Vue 3 + TypeScript + Vite
# static-web-templates
This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
A template-based solution for inflating different types of content without the need for a server or database.
## Recommended IDE Setup
## Local Development
- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
These instructions will try to be as thorough as possible and/or link to necessary references as much as possible in order for those who may not be used to this sort of development environment.
## Type Support For `.vue` Imports in TS
### Git
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types.
TBA
If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps:
### Node / NPM
1. Disable the built-in TypeScript Extension
1. Run `Extensions: Show Built-in Extensions` from VSCode's command palette
2. Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
Make sure you have node installed on your machine. The best way to manage node is to use [nvm](https://github.com/nvm-sh/nvm) ([windows version](https://github.com/coreybutler/nvm-windows)). This project uses `.nvmrc` to inform `nvm` of the targeted (ideal) version to use. Running `nvm install {version-in-nvmrc}` will install the appropriate version, and running `nvm use` in every terminal session will keep node in sync with `.nvmrc` (if the version is not installed, `nvm` will tell you what version to install). Once node is installed, run `npm ci` in a terminal to install the dependencies used by the project.
### Content
You will need to create a folder `/content` (ignored by `git`), add the basic site config to it, and have some sort of content in order for the site to generate. See [Architecture](#architecture) for more information.
### Live Preview
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
## Architecture
TBA
## Background
> As an artist, I wanted a way to share my art online without restrictions regarding content or niche. I also wanted a way to show a list of my games all in one spot for my developer alias. On top of that, I needed a way to showcase a portfolio of all my development projects for work/job searching. And finally, I wanted a landing website that simply linked to all other profiles I have and provide a sort of bio. These are several different websites, but all were similar in function: they were websites which all statically displayed dynamic content (static meaning that there is no server-side processing or reaction to user input). With the individual sites needs, the idea of creating templates for these goals came to be. To determine how the sites should be set up, I broke down the needs these sites shared:
>
> 1. it needed to be hosted in a cost-effective way
> 2. it needed to be easy to manage the content without rebuilding the full site
> 3. it needed to keep the content separate from source code in order to:
> 3a. make the templates re-usable under different aliases (developer versus personal)
> 3b. avoid any personal information being permanently committed in version control that could change or need to be removed
>
> With those needs in mind, after several iterations, this project's main architecture came to be. The result is a website generator that takes a configuration file, builds static routes from it, and the resulting static pages fetch the content and inflate it into the templates. It is essentially a static site generator with client-side rendering for the content, where the content is database-less flatfiles associated with the routes that were generated. Other static site generators require that your content be part of the build process, which could mean committed all content as part of source code and requires rebuilding the full site just to make a small change in text on a page. This retains the flexibility of dynamically-changing content while still providing a static site that can be hosted without any strange routing problems that you may get with vanilla frameworks that are solely client-side rendered single-page apps (e.g. the "#" present in URLs that's bad for SEO, or the need to redirect to index.html if said "#" is deactivated). The router will still perform as if it were a normal client-sided single-page app, retaining shared content such as site navigation and global styles between pages (instead of flashing white). But direct navigation to a given URL will work as well without any need to redirect all requests to HTML or any need to use "#" routing.
>
> In less technical terms: the site feels like a modern website but works more classically and without any need for a server, database, or other costly solution for hosting. This means you can just build the files and dump them on a free/cheap static host, and you can update content (add new images to a gallery, fix a type on a single About Me page, etc.) without rebuilding the whole site.
>
> This is a very niche project which probably won't be useful to many, but for those who want the benefits of modern web frameworks without the downsides, for those who want the main site to just be built once in a blue moon and can just change some content whenever they need to, and for those who don't want to pay a lot or be limited by third party hosts/builders/services for a simple website, this project is made for that.