[GPT-1] chore: update read me #197
Conversation
soloplxya
commented
Dec 10, 2022
soloplxya
commented
- Includes more information regarding
- Folder structure
- Key technologies used
soloplxya
requested review from
a team and
wei2912
and removed request for
a team
| - Partials | ||
| - The Partial folder contains reusable template components that can be used by other templates. These reusable template components serve to simplify the development process as we can reuse similar template components without having to code them from scrtch all over again. | ||
| - Handlebar Files (`.hbs`) | ||
| - Handlebars can be though of as a **language** that is used to construct template components. There are various other similar templating languages, some that you might be familiar with (for eg. `jsx` files (in React) or `html` files). |
There was a problem hiding this comment.
Did you mean something other than html files?
|
|
||
| This purpose of this section is to help developers to gain a more comprehensive understanding regarding the different components that are needed for ghost development. | ||
|
|
||
| - Partials |
There was a problem hiding this comment.
Would be good to include the exact path here (and perhaps refer to the folder as partials/ everywhere, rather than naming it, just to be clear)
| This purpose of this section is to help developers to gain a more comprehensive understanding regarding the different components that are needed for ghost development. | ||
|
|
||
| - Partials | ||
| - The Partial folder contains reusable template components that can be used by other templates. These reusable template components serve to simplify the development process as we can reuse similar template components without having to code them from scrtch all over again. |
There was a problem hiding this comment.
This line here seems a bit redundant (also "scratch" was misspelled)
| - Handlebar Files (`.hbs`) | ||
| - Handlebars can be though of as a **language** that is used to construct template components. There are various other similar templating languages, some that you might be familiar with (for eg. `jsx` files (in React) or `html` files). | ||
| - Ghost themes uses Handlebars for their templating language, and also includes some additional features such as layout and partials. | ||
| - Handlebar files can also be easily customized through modifications of the custom theme settings in the `package.json` file placed at the root directory of the project. |
There was a problem hiding this comment.
Do you think it'd be useful to elaborate on this? As far as I know the theme settings haven't been documented anywhere and I think it's not clear to new devs how those settings work (iirc they also show up in the Ghost design panel).
| - Handlebars can be though of as a **language** that is used to construct template components. There are various other similar templating languages, some that you might be familiar with (for eg. `jsx` files (in React) or `html` files). | ||
| - Ghost themes uses Handlebars for their templating language, and also includes some additional features such as layout and partials. | ||
| - Handlebar files can also be easily customized through modifications of the custom theme settings in the `package.json` file placed at the root directory of the project. | ||
| - Static Folder |
There was a problem hiding this comment.
Use exact path as mentioned above with partials.
| - Static Folder | ||
| - The static Folder contains files that do not change when the application is running. As such, they are not required to be rendered dynamically. | ||
| - Some examples of what can be stored in the static folder include: | ||
| - Scripts (`.js) |
| - Build process | ||
| - What is the difference between `npm run dev` and `npm run start`? | ||
| - `npm run dev` is used to run or view the application worked on while in development mode. When developing new features, this would be the more appropriate build command to use - as it renders changes onto your local build without having you to restart the server. | ||
| - `npm run start` is used to run the application in production mode. Changes made to the code base will not be reflected on the website when production mode is used. |
There was a problem hiding this comment.
I think the command is usually npm start, and it doesn't actually work since we don't have a start script in this repository. Here's the list of scripts:
Perhaps we could list out the scripts that are available and briefly explain what they do. As for npm start, it would be good to clarify that while we can start the build process with npm run dev, unlike with Create React App this does not open up a server for development changes, and one will have to run Ghost (along with the speedy development setup) or simply do npm run zip and upload the theme to see changes.
| ## Key Technologies that you might want to read up on | ||
|
|
||
| - TailWind CSS (https://tailwindcss.com/docs/installation) | ||
| - Handlebars (https://handlebarsjs.com/guide/) | ||
| - Javascript (https://developer.mozilla.org/en-US/docs/Web/JavaScript) |
There was a problem hiding this comment.
This bit can be incorporated into the above (maybe just link to Tailwind and Handlebars)
There was a problem hiding this comment.
Explain in prose what we use these for, and point out to use the Ghost variant of Handlebars
There was a problem hiding this comment.
please change embedded link from the latest Node.js version to that of v16 link: https://nodejs.org/en/blog/release/v16.16.0/
There was a problem hiding this comment.
Other things to do:
- Standardise Contributing section with [MPT-22] README update mentorship-page#548
- Change "Folder Structure" to "Project Structure", place a section for "Project Architecture" before this section explaining briefly how Ghost works (static site generator architecture/JAMstack and how it differs from WordPress) and what the theme files does
- Explain briefly how to create custom pages in the theme and how to make them appear on Ghost
- Remove PostCSS section and copyright (but not the actual LICENSE)
|
Would be good to add some supplementary info on Tailwind and Alpine.js (just a few lines of summary), and also linking to Tailwind component resources. |
|
Also add details on importing content from existing website. |
