Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[GPT-1] chore: update read me #197

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[GPT-1] chore: update read me #197

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,33 @@ Finally, run `npm run dev` in the `content/themes/dawn-advisory-theme/` director

This method is not officially supported by Ghost and might break any time (though the theme handling logic is unlikely to be modified in the foreseeable future). Take note that if you add new post templates, you may need to restart Ghost manually for the changes to take place in the Admin panel.

## Folder Structure

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean something other than 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

- Static Folder
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use exact path as mentioned above with partials.

- 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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing backtick here

- Style Sheets (`.css`)
- Images (profile pictures, header images... )
- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

image

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)
Comment on lines +84 to +88
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This bit can be incorporated into the above (maybe just link to Tailwind and Handlebars)

Copy link
Member

@wei2912 wei2912 Mar 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explain in prose what we use these for, and point out to use the Ghost variant of Handlebars


## `routes.yaml` Setup

For the homepage and separate [Stories](https://beta.advisory.sg/stories) page to be rendered correctly, it is necessary to upload a custom `routes.yaml` file onto Ghost. Please refer to [the instructions here](https://ghost.org/docs/themes/routing/) for more details.
Expand Down