api-platform/website

The API Platform website

api-platform.com

This repository contains the source code and documentation powering api-platform.com.

Single Page Application built with React and powered by Next.js.

Project structure

The project has been created from the API Platform distribution folder. All next.js application code is located in the "pwa" folder. The project is made with the Next.js new app router.

🤝 Contributors features

You need to use a valid github token to retrieve the list of contributors.

1. Go to your github developer settings

2. Select scopes public_repo, read:org and read:user, generate the token and copy it.

3. If you use "pnpm dev" on the folder pwa to launch the project, add a new .env.local file on the root of pwa folder, and set your token as an environment variable named GITHUB_KEY.

If you use docker, create a file "secret_github_key" at the root of the project with your token inside :

# Create the secret_github_key file
echo "YOUR_GITHUB_TOKEN" > secret_github_key

❗Core team badges restriction: You need to be a member of API Platform organization to retrieve API Platform teams. You can still locally launch the project, but the badges of the core team members will not appear.

Installation and usage

with docker

# Checkout project
git clone https://github.com/api-platform/website.git

# Change directory
cd website

# Create the github_key file
echo YOUR_GITHUB_TOKEN > secret_github_key

# Install and run the project locally
docker compose up -d
> Go to http://localhost

without docker

# Checkout project
git clone https://github.com/api-platform/website.git

# Change directory
cd website/pwa

phive install --trust-gpg-keys 62D05354C61458CB8378FD323F82299C64F51AD2 --copy https://github.com/php-documentation-generator/php-documentation-generator/releases/download/v0.0.0-beta.1/pdg.phar
bash tools/get-docs.sh
bash tools/get-core-docs.sh
bash tools/build-playground.sh
curl https://soyuka.me/contributors.json  -o ./data/contributors.json (commented in the playground)

# Install dependencies
pnpm install

# Launch prebuild script (necessary to create some images variants like wallpapers or logos, and to generate the contributors ranking)
pnpm prebuild

# Run project locally (for development)
pnpm dev
> Go to http://localhost:3000/

Build the project locally

with docker

# TO COMPLETE

without docker

# Build the project (for production) from the pwa folder
pnpm build

# Test the built project locally
pnpm start
> Go to http://localhost:3000

Publishing Docs For New Versions

1. Create a branch for the new version in the api-platform/docs repository.
2. Update consts.ts
3. Update Algolia crawler configuration

website's Issues

Add pretier to automatically fix CS

https://github.com/prettier/prettier
The integration done on our other JS components can serve as examples.

Links on page 404 don't work

Uncaught TypeError: Cannot read property 'push' of undefined
    at o (/app-7c443d8df45d2aa09e45.js:2)
    at /app-7c443d8df45d2aa09e45.js:2
    at Array.map (<anonymous>)
    at Object.emit (/app-7c443d8df45d2aa09e45.js:2)
    at a (/app-7c443d8df45d2aa09e45.js:1)
    at /app-7c443d8df45d2aa09e45.js:1
    at /app-7c443d8df45d2aa09e45.js:1
    at /app-7c443d8df45d2aa09e45.js:1
    at /app-7c443d8df45d2aa09e45.js:1
    at i (/app-7c443d8df45d2aa09e45.js:2)
o @ /app-7c443d8df45d2aa09e45.js:2
(anonymous) @ /app-7c443d8df45d2aa09e45.js:2
emit @ /app-7c443d8df45d2aa09e45.js:2
a @ /app-7c443d8df45d2aa09e45.js:1
(anonymous) @ /app-7c443d8df45d2aa09e45.js:1
(anonymous) @ /app-7c443d8df45d2aa09e45.js:1
(anonymous) @ /app-7c443d8df45d2aa09e45.js:1
(anonymous) @ /app-7c443d8df45d2aa09e45.js:1
i @ /app-7c443d8df45d2aa09e45.js:2
(anonymous) @ /app-7c443d8df45d2aa09e45.js:2
window.webpackJsonp @ /commons-7ce65b0cc81cb8c12a19.js:1
(anonymous) @ path---index-a0e39f21c11f6a62c5ab.js:1

"PREVIOUS CHAPTER" and "NEXT CHAPTER" links on the bottom of each documentation pages are broken.

Website version(s) affected: current

Description
"PREVIOUS CHAPTER" and "NEXT CHAPTER" links on the bottom of each documentation page are broken.

How to reproduce
For example, visit https://api-platform.com/docs/distribution/ and click on NEXT CHAPTER: TESTING THE API >

Your browser will return an error : docs’s server IP address could not be found.

Possible Solution
Links are missing root domain name ; They look like this :https://docs/distribution/testing/

When links should look something like this https://api-platform.com/docs/distribution/testing/

Additional Context
I would gladly help, but I have no experience with Gatsby so I have no idea how it can be fixed.

I believe it shouldn't be too difficult though.

Hope that helps, and thank you for awesome tool.

Add a link "edit this page" on every doc entries

It must redirect to the "edit" page on GitHub. For instance: https://github.com/api-platform/docs/edit/2.3/core/serialization.md

It must automatically create the link to the current default branch (not master, not an outdated branch).

Possible implem:

• detect the default branch in the clone of the docs repo retrieved by bin/retrieve-documentation
• add it to the outline.yaml file

Algolia search return duplicated results

One solution can be to display the doc item version to the search results box or simply ignore duplicated results?

Display the names of doc contributors at the end of docs entry

Display the list of contributors to a specific doc entry. Display only their GitHub avatar and a link to their GitHub account.

Calavera should be used to do that. It is already able to extra such data: https://github.com/dunglas/calavera/blob/master/extractor/git.go#L53

Related to #60

Change the meta tags according to the current page

Currently, the content of meta tags (OpenGraph, description...) is hardcoded. It would better for SEO and SMO to change them according to the current page.

The lines too change are here: https://github.com/api-platform/website/blob/master/src/templates/doc.js#L14

Redirect /docs/ to the first entry of the doc instead of a 404

Create the metadata-2.0.xsd file

According to api-platform/docs#255, we have to create the ./schema/metadata/metadata-2.0.xsd file.

Missing space in homepage (ApiPlatform <3 Symfony)

Hi,
There is a missing space between 'Doctrine ORM' and 'and all included' in the ApiPlatform ❤️ Symfony block.

The default distribution of API Platform is a perfectly valid Symfony full-stack application that follows Symfony's Best Practices. It also includes the famous Doctrine ORMand all included tools can leverage it.

Move the outline.yaml file to the docs repo

Fix Gatsby warnings

warning Your site's "gatsby-node.js" used a reserved field name in the context object when creating > a page:

• "path"

Rename /docs/core/index to /docs/core

Same for all indexes in the docs for compatibility with the old website and cleaner URLs.

It would also be nice to add 301 from /index to /.

Standardize trailing slashes

Sometimes links have trailing slashes, sometimes no. This need to be made uniform.

Remove /index from prev and next links

https://api-platform.com/docs/core/getting-started

This link points to https://api-platform.com/docs/core/index instead of https://api-platform.com/docs/core/

Add new references

The following references should be added:

• AudienceHero in "Open Source projects": https://github.com/AudienceHero/AudienceHero
• Orange in companies

404 due to multiple version new feature

Problem

At least one URL in documentation link to 404 due to the new feature of versionning.
/docs/current/ was fine before but isn't anymore.

Missing page

https://api-platform.com/docs/current/core/extensions/
from
https://api-platform.com/docs/core/filters/#creating-custom-filters
When you click on "Extensions"

This case may be at other places, /current/ should be replace with /

Missing key prop in docs

Reproducer: http://localhost:8000/docs/master/distribution/

Warning: Each child in a list should have a unique "key" prop.

Check the render method of `Template`. See https://fb.me/react-warning-keys for more information.

Image is not loaded on api-platform.com

@borNfreee:

Image about serializer (on the very beginning of the article) is not loaded on https://api-platform.com/docs/core/serialization/#the-serialization-context-groups-and-relations while it works in https://github.com/api-platform/docs/blob/2.3/core/serialization.md

(Moved from api-platform/docs#538)

Improve accessibility and SEO

• use h1 tag only for top-level headings only
• use h2-h6 tags for all articles
• use h2-h6 tags for all sections

Add a "contributors" page

This page new page will display the list of all API Platform contributors.

• It must display the name of the contributor, it's GitHub avatar, and have a link to his GitHub account
• Contributors must be ordered by number of contributions
• The name of repositories the user contributed to must be displayed below his name (ex : core, docs, api-doc-parser).

It should extract the list of contributors using the GitHub API or by cloning the Git repositories directly. The process must be 100% automated.

Possible implementation:

• Use the GitHub API to list all the repositories under the api-platform org
• Clone all those repositories
• Extract the list of contributors and their number of commits using Git
• Group by email

Filter unwanted input in anchors

Some anchors contain "sanitized" unwanted markdown code: https://api-platform.com/docs/core/data-providers/#injecting-the-serializer-in-an-code-classlanguage-textitemdataprovidercode

code-classlanguage-textitemdataprovidercode

Such patterns must be filtered.

The menu is not open when coming to the page directly

Go directly to https://api-platform.com/docs/core/filters#boolean-filter

The left menu should be open and should display the inner links. The scroll spy should work. This isn't the case.

Mobile version: hamburger menu should retract when scrolling

Reported by @CecileAmrl

(ios 10.0.1)

Patch files should be highlighted

Thepatch format is supported by GitHub in Markdown documents but not on our website.
It looks like Prism (used by Gatsby) doesn't support it. We should add support for patch in Prism.

Update to Gatsby v4 and more recent dependencies

Description
Hello,
One of my side projects website is based on this project. Thanks a lot for it.
I recently spent some time upgrading dependencies to more recent versions, including to Gatsby 4.

I was wondering if you are interested in me opening a MR doing the same for API Platform website. It would a way for me to contribute back to this project.

Example

Here is what I've done on my side: n7consulting/jeyser-site#14

Tables are too wide

For example: https://api-platform.com/docs/core/events/#the-event-system

Wrong documentation order when switching versions

If you take the Client Generator documentation page :
https://api-platform.com/docs/master/client-generator/

If you switch between master and current version the order of the docs, seen on sidebar, is different (troubleshooting going from last position to 4th position for example)

Bottom page navigation is missing

Before on every documentation pages there were buttons at bottom : previous chapter and next chapter.

Seems missing since versions switching update

Pages marked as "noindex" are present in sitemap.xml

To improve the quality of the search result, all documentation pages for specific versions (such as ) are marked as "noindex", so only the current documentation is indexed by Google and other search engines.

However, the sitemap contains these URLs. They must be removed from the sitemap: https://api-platform.com/sitemap.xml

Support formats tabs

Implement formats tabs on documentation parsing.

Example: https://symfony.com/doc/current/reference/constraints/All.html#basic-usage

API Platform Con 2021 review: add an additionnal button on the homepage

Add on this homepage (https://api-platform.com/con/2021/review) a button "Watch the conferences"

This button should be linked to this playlist: https://www.youtube.com/playlist?list=PL3hoUDjLa7eSo7-CAyiirYfhJe4h_Wxs4

Add Schema.org markup

Add the following Schema.org markup to all the pages (including the main page):

• https://schema.org/WebPage

Add the following to all docs page:

• https://schema.org/CreativeWork

https://github.com/dunglas/calavera can be used to extract the relevant metadata from the Git repository. Creating an integration between Calavera and Gastby (a Calavera transformer) would be the best solution.

Calavera is able to generate directly the proper JSON-LD markup (related to #60 and #61).

Rework markup SC player

• At the moment, the SC image is not displayed, if there is no caption - this is a bug (due to gatsby-remark-images plugin).

Details

Page - https://api-platform.com/docs/master/distribution/

• When you hover over an caption with an SC image, background of the entire clickable area is highlighted, it seems to me that it is wrong and ugly, the hover effect should be applied only to the caption.

Details

Page - https://api-platform.com/docs/deployment/

Should be like this:

What do you think, @dunglas?

Nav script generation doesn't handle h3

index.md

7.  [The Serialization Process](core/serialization.md)
    1.  [Overall Process](core/serialization.md#overall-process)
    2.  [Available Serializers](core/serialization.md#available-serializers)
    3.  [The Serialization Context, Groups and Relations](core/serialization.md#the-serialization-context-groups-and-relations)
        1.  [Configuration](core/serialization.md#configuration)

Expected in nav.yml :

- id: serialization
      title: The Serialization Process
      anchors:
        - id: overall-process
          title: Overall Process
        - id: available-serializers
          title: Available Serializers
        - id: the-serialization-context-groups-and-relations
          title: 'The Serialization Context, Groups and Relations'
          anchors:
            - id: configuration
              title: Configuration

Getting started documentation link is broken

https://api-platform.com/docs/core/getting-started/#before-reading-this-documentation is where the broken link can be found. I personally believe it does affect all links to every index.md file too.

Update the dependencies

Update all the JS deps to their latest versions.

Community showcase

Do you want to showcase more projects? Could we have our logo added here?

website/app/views/main.html

Line 258 in 5c900e3

<img src="images/logos.png" alt="The Fork, Smile, PartKeepr, ExaqtWorld, Les-Tilleuls.coop" width="937" class="img-responsive">

Release documentation for 2.7

TODO:

• redirect data-provider and data-persister to state-provider and state-processor
• do a quick link from the home page to the upgrade guide when releasing a 2.7
• change the background ? (ping @ginifizz @dunglas )

Align text list item

Before (right now)	After

This will also fix such a bug! (page - https://api-platform.com/docs/v2.2/client-generator/troubleshooting/)

Are we doing this or not, @dunglas?

Investigate the cache issue

After each deployment, the site is broken during some minutes / hours. Probably because of cache issue related to service workers.

Improve accessibility

According to W3 ARIA, followings issues should be considered:

• meta tag should not include mutiple attributes.
  ex: put charset attribute in a separated meta tag.

• type attribute for style element is not needed and should be omitted.

• value fetch is not allowed for as attribute on link tag

Anchor padding when navigating

When using the anchors in the doc (either by using the summary on the left, or accessing a url like this one : https://api-platform.com/docs/distribution/#a-bookshop-api), the desired title is not at the top. In reality, it's at top but the sticky menu is hiding it. Front-end/integration issue, but not my scope so can't really help more sorry !

tested on :
Firefox 85.0.2
Chrome 88.0.4324.182

Search engine doesn't take the version into account

It looks like the Algolia search engine only returns results from the current documentation, regardless of the version you're actually reading (e.g. 2.4).

Is it something easily fixable?

[Mobile] Website is too large

Chrome 53.0.2785.124
Android 6.0.1
Resolution 1080 x 1920 pixels

Error while installing the project

What i did :

• git clone project
• yarn
• bin/retrieve-documentation -> error missing file debugging.md in distribution section in config/outline.yaml

Add MBT Bundle to Open Source Projects

https://mbtbundle.org/

Uses API Platform + Admin (https://github.com/tienvx/mbt-api-bundle/blob/master/composer.json#L22, https://github.com/tienvx/mbt-admin/blob/master/package.json#L6).

Improve accessibility

According to W3 ARIA, followings issues should be considered:

• Burger button does not have an accessible name.

• Links to Twitter and Github in menu don't have discernable names.

• In the burger button div is not allowed as child of button in this context

• <html> element does not have a [lang] attribute.

• frameborder attribute for iframe tag is obsolete, use CSS instead.

• scrolling attribute for iframe tag is obsolete, use CSS instead.

• Stray start tag script.

API Platform Con 2021: add conference recordings on each talk description

Add above each talk description the corresponding conference recording

Example
Add on Antoine's page this video: https://www.youtube.com/watch?v=hxTJPt06jjM
All videos can be found on this playlist: https://www.youtube.com/playlist?list=PL3hoUDjLa7eSo7-CAyiirYfhJe4h_Wxs4
All talks descriptions can be found on this schedule: https://api-platform.com/con/2021/#schedule

Thanks!

"Edit on GitHub link" is broken

The change introduced by #72 is broken.

https://api-platform.com/docs/core/serialization/#the-serialization-process

The generated URL is https://github.com/api-platform/docs/edit/undefined/core/serialization.md...
Can you fix this @Mathieudewet please?

By the way the test of the link should be "Edit this page on GitHub".