|
1 |
| -# hello-astro |
| 1 | +# Hello Tham Website (Astro) |
2 | 2 |
|
3 |
| -Hello Astro is a full featured [Astro](https://astro.build) multi-purpose starter theme written in Typescript and TailwindCSS. It supports Markdown and MDX based pages and blog posts. |
4 |
| - |
5 |
| - |
6 |
| - |
7 |
| - |
8 |
| - |
9 |
| - |
10 |
| - |
11 |
| -Hello Astro can used for any/all of the following: |
12 |
| - |
13 |
| -- corporate/marketing site |
14 |
| -- blog |
15 |
| -- documentation site |
16 |
| -- portfolio site supporting photo galleries |
17 |
| - |
18 |
| -Uses the following integrations: |
19 |
| - |
20 |
| -- @astrojs/mdx |
21 |
| -- @astrojs/markdoc |
22 |
| -- @astrojs/sitemap |
23 |
| -- @astrojs/rss |
24 |
| -- @astrojs/tailwind |
25 |
| -- @astrojs/alpinejs |
26 |
| -- astro-icon |
27 |
| -- astro-seo |
28 |
| -- astro-robots-txt |
29 |
| - |
30 |
| -In addition, SVG and PNG illustrations sourced from [Undraw](https://undraw.co) |
31 |
| - |
32 |
| -This project initially started as a bare bones port of [hello-gatsby-starter](https://github.com/hellotham/hello-gatsby-starter), but now contains more features (light/dark modes, category pages, search, diagrams, math and more!) |
33 |
| - |
34 |
| -## Features |
35 |
| - |
36 |
| -- Full-featured blog with frontmatter (title, description, author, date, image, tags) |
37 |
| -- High performance low overhead with minimal Javascript (AlpineJS) |
38 |
| -- Full text client based search of blog pages via lunrjs (search index only loaded on first invocation of search on a page) |
39 |
| -- Index page and individual pages for authors, categories and tags, including pagination |
40 |
| -- Support for RSS feed, sitemap and robots.txt |
41 |
| -- SVG design (unDraw, Hero Patterns, Iconify) |
42 |
| -- Support for code syntax highlighting |
43 |
| -- Full SEO support including Open Graph, Twitter Cards and Schema.org via JSON-LD |
44 |
| -- Full support for Light and dark UI modes, as well as following system preferences, in accordance to TailwindCSS recommendation |
45 |
| -- Customised 404 error page |
46 |
| -- Display math equations using KaTeX via remark-math/rehype-katex (enclosed in `$`...`$` or `$$`...`$$`) |
47 |
| -- Display Mermaid, Markmap, PlantUML diagrams (authored as a code block with language `mermaid`, `markmap` and `plantuml`) |
48 |
| -- Display map at geo coordinates and zoom level using `Map` component (need to also include `extra: ['map']` is frontmatter to load CSS/JS assets for page) |
49 |
| -- Calculates and show reading time for blog posts |
50 |
| -- CSS/JS assets of external libraries loaded only when needed on a per page and per package basis - no unnecessary bloat |
51 |
| -- Photo gallery and lightbox using PhotoSwipe (including display of EXIF tags) |
52 |
| -- Carousel component using Swiper |
53 |
| -- Documentation pages (modelled after astro docs starter but using Tailwind) |
54 |
| - |
55 |
| -## External Packages |
56 |
| - |
57 |
| -The start uses the following external packages: |
58 |
| - |
59 |
| -- [Astro](https://astro.build/) |
60 |
| -- [TypeScript](https://www.typescriptlang.org/) |
61 |
| -- [TailwindCSS](https://tailwindcss.com) and [TailwindUI](https://tailwindui.com) |
62 |
| -- [Iconify](https://iconify.design/) |
63 |
| -- [Hero Patterns](https://heropatterns.com/) |
64 |
| -- [unDraw](https://undraw.co/) for illustrations |
65 |
| -- [MDX](https://mdxjs.com/) and [Markdown](https://www.markdownguide.org/) |
66 |
| -- [Schema.org](https://schema.org/) and [JSON for Linking Data](https://json-ld.org/), type-checked using [schema-dts](https://github.com/google/schema-dts) |
67 |
| -- [Open Graph](https://ogp.me/) used by [Facebook](https://developers.facebook.com/docs/sharing/webmasters/#markup) |
68 |
| -- [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards) |
69 |
| -- [AlpineJS](https://alpinejs.dev) |
70 |
| -- Local full text search using [Lunr](https://lunrjs.com) |
71 |
| -- Math equations using [KaTeX](https://katex.org) via [remark-math and rehype-katex](https://github.com/remarkjs/remark-math) |
72 |
| -- Diagrams using [Mermaid](https://mermaid-js.github.io/mermaid/#/), [Markmap](https://markmap.js.org) and [PlantUML](https://plantuml.com) |
73 |
| -- Open Street Map using [Leaflet](https://leafletjs.com/) |
74 |
| -- [reading-time](https://github.com/ngryman/reading-time) |
75 |
| -- [PhotoSwipe](https://photoswipe.com) |
76 |
| -- [exifr](https://mutiny.cz/exifr/) |
77 |
| -- [Swiper](https://swiperjs.com/) |
78 |
| -- [Remark Emoji](https://github.com/rhysd/remark-emoji) |
79 |
| - |
80 |
| -It follows the [JAMstack architecture](https://jamstack.org) by automatically building a static version from the Git repository. The demo is deployed on Github Pages. |
81 |
| - |
82 |
| -## 🚀 Project Structure |
83 |
| - |
84 |
| -Inside this starter, you'll see the following folders and files: |
85 |
| - |
86 |
| -```text |
87 |
| -/ |
88 |
| -├── public/ |
89 |
| -│ └── favicon.ico |
90 |
| -├── src/ |
91 |
| -│ ├── assets/ |
92 |
| -│ │ ├── image.png |
93 |
| -│ │ └── gallery/ |
94 |
| -│ │ └── gallery-name/ |
95 |
| -│ │ └── image.jpg |
96 |
| -│ ├── components/ |
97 |
| -│ │ └── header.astro |
98 |
| -│ ├── content/ |
99 |
| -│ │ ├── blog/ |
100 |
| -│ │ | └── 2022-08-01-post.md |
101 |
| -│ │ ├── doc/ |
102 |
| -│ │ | └── documentation-page.md |
103 |
| -| │ └── config.ts |
104 |
| -│ ├── layouts/ |
105 |
| -│ │ ├── base.astro |
106 |
| -│ │ ├── blog.astro |
107 |
| -│ │ └── doc.astro |
108 |
| -│ ├── pages/ |
109 |
| -│ │ ├── index.astro |
110 |
| -│ │ └── contact.astro |
111 |
| -│ └── config.ts |
112 |
| -└── package.json |
113 |
| -``` |
114 |
| - |
115 |
| -Astro looks for `.astro`, `.md` or `.mdx` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. |
116 |
| - |
117 |
| -`src/components/` is where we put any Astro components and similarly `src/layouts/` for layouts. |
118 |
| - |
119 |
| -Images can be placed in `src/assets/`. |
120 |
| - |
121 |
| -Blog and documentation content are created as collections of Markdown or MDX files in `src/content`. |
122 |
| - |
123 |
| -Any static assets, eg. images, can be placed in the `public/` directory. |
124 |
| - |
125 |
| -## 🧞 Commands |
126 |
| - |
127 |
| -All commands are run from the root of the project, from a terminal: |
128 |
| - |
129 |
| -| Command | Action | |
130 |
| -| :------------------ | :------------------------------------------------- | |
131 |
| -| `pnpm install` | Installs dependencies | |
132 |
| -| `pnpm dev` | Starts local dev server at `localhost:3000` | |
133 |
| -| `pnpm build` | Build your production site to `./dist/` | |
134 |
| -| `pnpm preview` | Preview your build locally, before deploying | |
135 |
| -| `pnpm lint` | Pretty print the source code | |
136 |
| -| `pnpm check` | Check the source code for errors | | |
137 |
| -| `pnpm astro ...` | Run CLI commands like `astro add`, `astro preview` | |
138 |
| -| `pnpm astro --help` | Get help using the Astro CLI | |
139 |
| - |
140 |
| -## Release History |
141 |
| - |
142 |
| -- 1.0.0: Initial Release |
143 |
| -- 1.0.1: Moved social images to src, improved coverImage processing |
144 |
| -- 1.0.2: Upgrade packages to latest |
145 |
| -- 1.1.0: Update to astro v2.x, now works with node 18 and 19 |
146 |
| -- 2.0.0: New version supporting Astro collections! Also clarified that this is a |
147 |
| - multipurpose theme. Search can now include both Markdown and MDX pages! |
148 |
| -- 2.0.1: Updated screenshots, and improved landing page. |
149 |
| -- 2.1.0: updated to latest packages, fixed dev links, backported features from |
150 |
| - personal blog, including Next/Prev links, photo gallery support in Markdown, |
151 |
| - and improved pagination control. |
152 |
| -- 2.2.0: Fixed lint errors, reimplemented map, lightbox and carousel to use |
153 |
| - leaflet, photoswipe and swiper packages instead of relying on external CDN. |
154 |
| -- 2.2.1: Update to astro 2.0.10, fixed asset loading issue with base |
155 |
| -- 2.3.0: Removed layout from blog and doc content |
156 |
| -- 2.4.0:`@astrojs/images` now support `svg` so no need for special handling |
157 |
| -- 2.4.1: Use rendered frontmatter for blog and doc posts, fixes issue with diagrams not rendering. |
158 |
| -- 2.4.2: Updated packages |
159 |
| -- 3.0.0: Major update: |
160 |
| - - Use new Astro optimised asset support |
161 |
| - - new Astro logo |
162 |
| - - optimised post draft filtering |
163 |
| - - cleaned up gallery |
164 |
| - - fixed up SEO errors |
165 |
| - - cleaned up lint errors |
166 |
| - - migrated authors and categories to collections and use referential integrity based on Astro 2.5.0 |
167 |
| - - converted social links to a data collection (requires Astro >2.5.0) |
168 |
| - - updated favicon and header metadata |
169 |
| - - improve search to include documentation |
170 |
| -- 3.1.0: Enhancement update: |
171 |
| - - Migrated package manager from yarn to pnpm |
172 |
| - - Reference base for head links |
173 |
| - - Added eslint and prettier with plugins |
174 |
| - - Fixed image attributes error in seo component |
175 |
| - - Updated tsconfig to match astro strict |
176 |
| - - Update Katex CSS link |
177 |
| - - Fixed author not appearing in blog card |
178 |
| - - Added Markdoc support |
179 |
| -- 3.1.1: Minor update: |
180 |
| - - Lazy load images |
| 3 | +This is the Hello Tham Corporate Website Static Web App built using the |
| 4 | +[Hello Astro](https://github.com/hellotham/hello-astro) starter. This version is deployed on Github Pages. |
0 commit comments