Skip to content

Fix template docs for v4 #665

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

Jump to bottom
Merged
merged 22 commits into from
Jan 9, 2023
Merged

Fix template docs for v4 #665

merged 22 commits into from
Jan 9, 2023

Conversation

@remidej
Copy link
Collaborator

@remidej remidej commented Jan 20, 2022

Why is it needed?

v4 handles templates differently than v3. On v3, we used Github to host them. Now they are published as npm packages.

Some features were also removed on v4:

  • The shorthand feature was removed. npm package names are much shorter than Github URLs, so it was less useful. It also added some complexity to the docs. Now, only Strapi's official templates have a shorthand.
  • The dynamic template.js config feature was also removed. That's because templates can now be versioned with npm. So there's no need to dynamically generate the config, users should instead create a new template version instead.

@vercel
Copy link

vercel bot commented Jan 20, 2022 •
edited
Loading

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/strapijs/documentation/Hy1NqYVCvZNYWrdGm8gq6hKLEky6
✅ Preview: https://documentation-git-v4-templates-strapijs.vercel.app

@remidej remidej requested a review from pwizla January 20, 2022 16:24
derrickmehaffy
derrickmehaffy approved these changes Jan 24, 2022
View reviewed changes
Copy link
Member

@derrickmehaffy derrickmehaffy left a comment

Choose a reason for hiding this comment

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

lgtm (minus TW)

@pwizla
Copy link
Collaborator

pwizla commented Jan 26, 2022

Thank you for updating it, @remidej !
As we are trying to make sure that all new content now follows our 12 rules and style guide, I will take a bit more time in the next few days to review the PR thoroughly and add suggestions. Thank you for your patience.

@pwizla
Copy link
Collaborator

pwizla commented Jan 26, 2022

Also, we'll try to make sure this document is properly included in the TOC. For now, documentation for templates is only accessible by search.

@pwizla pwizla self-assigned this Jan 27, 2022
@pwizla pwizla added size: large If the PR includes 1+ file(s) with a total of 50+ lines of text or 100+ lines of code source: Dev Docs PRs/issues targeting the Developer Docs target: v4 Documentation PRs/issues targeting content from docs.strapi.io (main branch). internal PRs created by the Strapi core team labels Jan 27, 2022
pwizla added 7 commits January 27, 2022 17:37
pwizla
pwizla requested changes Jan 27, 2022
View reviewed changes
Copy link
Collaborator

@pwizla pwizla left a comment •
edited
Loading

Choose a reason for hiding this comment

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

Thank you again @remidej for this update!

I've done a thorough technical writing review of this file.
You will find:

  • suggestions that you can directly apply here on GitHub
  • content that I directly modified in subsequent commits (as I can't comment on lines that weren't modified by the PR)

Once suggestions are applied, we'll have to rethink the structure a bit as it's missing a clear path.

We could have something like:

  • using a template
  • creating a template:
    • requirements
      • intro with the 3 requirements (template folder, package.json, template.json)
      • template folder requirements (allowed files)
      • template.json requirements
    • package creation and publication on npm

We can discuss it further if you need help.

@remidej @pwizla
Update docs/developer-docs/latest/setup-deployment-guides/installatio…
e27677d 
…n/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
remidej and others added 2 commits January 28, 2022 09:49
@remidej @pwizla
Update docs/developer-docs/latest/setup-deployment-guides/installatio…
5195261 
…n/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
@remidej @pwizla
Update docs/developer-docs/latest/setup-deployment-guides/installatio…
e418185 
…n/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
remidej and others added 3 commits January 28, 2022 09:51
@remidej @pwizla
Update docs/developer-docs/latest/setup-deployment-guides/installatio…
83961db 
…n/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
@remidej @pwizla
Update docs/developer-docs/latest/setup-deployment-guides/installatio…
29500fc 
…n/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
@remidej @pwizla
Update docs/developer-docs/latest/setup-deployment-guides/installatio…
0cf5521 
…n/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
@samuel-2018
Copy link

@pwizla @remidej Hi! Any progress on this? I’m interested in learning more about how Strapi templating works in version 4.

@pwizla
Copy link
Collaborator

pwizla commented Nov 3, 2022

Hi @samuel-2018, and thank you for your question. It has been deprioritized for now. In the meantime, you can still visit the temporary URL deployed with this PR here, and I can check with the team if we have the resources to publish a final version before the end of the quarter. Hope this helps :)

@remidej remidej mentioned this pull request Jan 5, 2023
Closed
@vercel
Copy link

vercel bot commented Jan 6, 2023 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated
documentation ✅ Ready (Inspect) Visit Preview 💬 Add your feedback Jan 9, 2023 at 9:45AM (UTC)
documentation-docu-mvp ❌ Failed (Inspect) Jan 9, 2023 at 9:45AM (UTC)

@pwizla
Copy link
Collaborator

pwizla commented Jan 9, 2023

Thanks for the updates, @gpene. Looks good to me, I'd suggest a few style-related updates:

  • replace app with application
  • I think we should reserve bold for UI elements, so I'd remove the bold formatting on "must" (line 79)

@gpene gpene merged commit 2dc0bb8 into main Jan 9, 2023
@gpene gpene deleted the v4-templates branch January 9, 2023 09:59
pwizla added a commit that referenced this pull request Jan 12, 2023
@pwizla @derrickmehaffy
@stb13579 @k8adev @swiersyoram @nikajorjika @gpene @rainx @michaelroth-xx @alanjc7 @remidej
🚀 Production release: Strapi v4.5.6 (#1405)
8b03649 
* Ignore me, just testing something (#1377)

* fix issue #1321

* fix logger middleware example. closes #1360

* fixes #1301

* Add missing parentheses

Parentheses are missing from some of the examples for v4.

* Added --no-cache and --production flags for docker

* update google-app-engine.md

* Fix/possible null returned (#1340)

* Fixing possible bug/error

Removed all the env helper function usages from anywhere but config file, per laravel documentation. ref: https://laravel.com/docs/9.x/helpers#method-env

If you execute the config:cache command during your deployment process, you should be sure that you are only calling the env function from within your configuration files. Once the configuration has been cached, the .env file will not be loaded and all calls to the env function will return null.

* Refactored config file example

- Removed unused entries from config file.
- Removed redundant comments, since it offers no additional information.

* Copy edit

Co-authored-by: Gabriel <83644514+gpene@users.noreply.github.com>

* Remove the duplicated `of` in the Troubleshooting document (#1392)

There is a useless `of` in the part `typical count of of component entries`

* Add possible Variable for user-permission emails

found this only in an issue on github: strapi/strapi#12771 
Would have saved me some time if I had found it earlier here :)

* Remove reference to Hobby Dev plan of Heroku Postgres add-on.

* Fix template docs for v4 (#665)

* Fix template docs for v4

* Reword introduction

* In our introductions, bullet lists are usually reserved for items that
will be described in sections of the current document (they act like a
mini-TOC (table of content)
* Avoid using "you" when not necessary (see our
https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing)

* Avoid overusing you. Write procedure-based instructions.

* Neutral tone + use of `(e.g. )` to list examples

* Use bullet points + `e.g.` + code blocks (for a prettier look)

* Avoid overusing you + example format consistent with the whole documentation

* Include important information in a caution callout if it could break the app

* Add link to file structure section

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>

* Apply piwi feedback

* Update docs/developer-docs/latest/setup-deployment-guides/installation/templates.md

* rework structure

* fix link

* typo fix

* feedback updates

Co-authored-by: Pierre Wizla <pwizla+github@gmail.com>
Co-authored-by: Pierre Wizla <pwizla@users.noreply.github.com>
Co-authored-by: Gabriel <83644514+gpene@users.noreply.github.com>

* add install command (#1393)

Co-authored-by: DMehaffy <derrickmehaffy@gmail.com>
Co-authored-by: Shaun Brown <shaun.brown@strapi.io>
Co-authored-by: Keit Oliveira <keit.oliveira@icloud.com>
Co-authored-by: Simen Daehlin <sdaehlin@luno.com>
Co-authored-by: Yoram Swiers <yoram@swiers.be>
Co-authored-by: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com>
Co-authored-by: Nika Jorjoliani <nikajorjika1993@gmail.com>
Co-authored-by: Gabriel <83644514+gpene@users.noreply.github.com>
Co-authored-by: RainX <101971+rainx@users.noreply.github.com>
Co-authored-by: michaelroth-xx <62610391+michaelroth-xx@users.noreply.github.com>
Co-authored-by: Alan Carrie <alanjcarrie@gmail.com>
Co-authored-by: Rémi de Juvigny <8087692+remidej@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@derrickmehaffy derrickmehaffy derrickmehaffy approved these changes

@pwizla pwizla Awaiting requested review from pwizla pwizla is a code owner

Assignees

@pwizla pwizla

Labels

internal PRs created by the Strapi core team size: large If the PR includes 1+ file(s) with a total of 50+ lines of text or 100+ lines of code source: Dev Docs PRs/issues targeting the Developer Docs target: v4 Documentation PRs/issues targeting content from docs.strapi.io (main branch).

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@remidej @pwizla @strapi-bot @samuel-2018 @derrickmehaffy @gpene