Update how-to-publish.md#461
Conversation
Add more detailed guidance on how to publish posts, including using codespaces and github in the browser
| You only need to create a Codespace once. After that, reopen it from the same 'Codespaces' tab. | ||
|
|
||
| ### Create your post | ||
|
|
There was a problem hiding this comment.
Might need to mention creating a new branch as the first step?
|
|
||
| Run `npm start` and visit `http://localhost:8080` at any point to preview locally. | ||
|
|
||
| ### Publish your post |
There was a problem hiding this comment.
This section includes all the git terminal commands. But would it be better to suggest using a git graphical user interface like the one built in to VS Code, or a separate app like GitHub Desktop?
veroje
left a comment
veroje
left a comment
There was a problem hiding this comment.
Thanks for writing these super helpful instructions!
Consider my github newbie comments.
I'm also thinking:
- could be good to use tabs to present this info (like Github documentation does it)
- could consider explaining each concept (PR, commit..) only once outside of the 'by method' instructions, like a glossary - this might help maintain these instructions and not having to make the changes 3 times
| 16. Go to the [DPSP design history repository on GitHub](https://github.com/NHSDigital/prevention-services-design-history) | ||
| 17. Click 'Pull requests' and find yours | ||
| 18. Click 'Compare & pull request' | ||
| 19. Update the title and description if needed – they should summarise your post |
There was a problem hiding this comment.
Would appreciate an example of the PR title, esp how it differs from commit title?
| 1. In the file explorer, find the `app` folder and your team's subfolder, for example `app/lung-health-check/` | ||
| 2. Create a new folder for your post using the year, month, and a short title, for example `app/lung-health-check/2026/03/designing-new-service/` | ||
| 3. Inside that folder, create a file called `index.md` | ||
| 4. Add the [frontmatter](#frontmatter) at the top of the file |
There was a problem hiding this comment.
If using the template this might be redundant
| Before adding images, compress them using [TinyPNG](https://tinypng.com/) to reduce file size. | ||
|
|
||
| 1. Drag and drop your images into the same folder as your `index.md` file | ||
| 2. Reference them in your Markdown using a relative path, for example: |
There was a problem hiding this comment.
Need to say more about the 'relative path' - perhaps with examples?
| 1. Click the 'Source Control' icon in the left sidebar | ||
| 2. Click the `...` menu, select 'Branch', then 'Create branch' – a branch is a separate copy of the files where you can make changes without affecting the main site | ||
| 3. Give your branch a name, for example `your-username/your-post-title`, and press Enter | ||
| 4. Type a short commit message, for example `Add post: your post title` – a commit saves a snapshot of your changes |
- removes front matter section - adds internal link - updates explanation of working locally - doesn't assume the user will save the file locally first
update description of repository root
- update images - give example of PR title
how to edit after preview
references the sample frontmatter
- pr process locally
@veroje thanks for these suggestions On tabs – we'd need to do quite a bit of work to make tabs like github – maybe one for another time. We could split this into 3 posts? if you think that would be easier to follow On the glossary – I think keeping definitions inline is better for this audience. Users don't need to read the whole page or remember terms before they start. |
4 participants
Add more detailed guidance on how to publish posts, including using codespaces and github in the browser