diff --git a/packages/vscode-graphql-syntax/README.md b/packages/vscode-graphql-syntax/README.md
index 598d64a3c1c..229bb15082a 100644
--- a/packages/vscode-graphql-syntax/README.md
+++ b/packages/vscode-graphql-syntax/README.md
@@ -1,56 +1,159 @@
 # GraphQL Syntax Support
 
-Adds basic GraphQL highlighting and language support such as bracket matching.
+Adds full GraphQL syntax highlighting and language support such as bracket matching.
 
-Supports `.graphql`/`.gql`/`.graphqls` highlighting
+- Supports `.graphql`/`.gql`/`.graphqls` highlighting
+- [Javascript, Typescript & JSX/TSX](#ts) & Vue
+- ReasonML/ReScript (`%graphql()` )
+- Python
+- PHP
+- [Markdown](#markdown)
+
+You'll want to install this if you do not use `graphql-config`, or want to use the highlighting with other extensions than `vscode-graphql`
 
-## Supported Languages
+## Embedded Language Usage
 
+<span id="ts">
 ### Javascript & Typescript
 
-accepted template strings and expression patterns
+The following delimiters are accepted for syntax highlighting. If you are using any of these patterns and they do not work, please open an issue!
 
-```typescript
-gql`
+#### Template Literal Expressions
+
+```ts
+const query = gql`
   {
     id
   }
 `;
-graphql`
+```
+
+you can use these template tag literal expressions anywhere you like of course
+
+```ts
+useFancyGraphQLClient(
+  graphql`
   {
     id
   }
-`;
-gql<MyType>`
+`, {
+  networkStrategy: 🚀
+ }
+)
+```
+
+```ts
+const query = gql.experimental`{ id }`;
+```
+
+and in typescript, template tag expressions with type arguments
+
+```ts
+const query = gql<MyType>`
   {
     id
   }
 `;
-gql.experimental`{ id }`;
 ```
 
-```typescript
-gql('{ id }');
-graphql('{ id }');
-gql<MyType>('{ id }');
-gql.experimental('{ id }');
+#### Function Expressions
+
+as well as normal function expressions with template literals
+
+```ts
+gql(`{ id }`);
+```
+
+```ts
+graphql(
+  `
+    {
+      id
+    }
+  `,
+);
 ```
 
-accepted comment-delimited patterns
+there is a bug with function expressions with type arguments like these that we need to fix:
+
+```ts
+gql<MyType>(`{ id }`);
+```
+
+Note, inline `""` and `''` string literals could also be delimited if needed, but we currently only delimit graphql template strings for obvious reasons
+
+#### Comment-Delimited patterns
 
 ```ts
 /* GraphiQL */
 const query = `
  { id }
 `;
+```
+
+```ts
 const query = `#graphql
  { id }
 `;
 ```
 
-- ReasonML/ReScript (`%graphql()` )
-- Python
-- PHP
-- Markdown for `graphql\`\``,`GraphQL\`\``and`gql\`\`` (even when deeply nested!)
-
 For full autocompletion, validation and other features, you can install `GraphQL.vscode-graphql`, which depends on this extension
+
+<span id="markdown">
+
+### Markdown
+
+#### backtick code blocks
+
+````markdown
+# Hello Jan
+
+```graphql
+  query MyQuery {}
+```
+````
+
+#### embedded graphql in js & ts codeblocks
+
+simple js/ts`gql` & `graphql` template tag expression support inside any backtick codeblocks.
+
+````markdown
+# Hello Jan
+
+```js
+string : X = gql`
+{
+  its {
+    query
+    time
+  }
+}
+```
+````
+
+## Other languages
+
+We actually support other languages than this! just need to extend this readme even further! 🥵
+
+## Publishing Notes
+
+Note: this extension has temporarily been published from [this PR](https://github.com/graphql/graphiql/pull/2573) until we are ready to re-release `vscode-graphql` with it as well.
+
+## Contributing
+
+Feel free to open a PR to fix, enhance any language support, or even add new languages 😍
+
+see:
+
+- [the grammars](grammars/)
+- [the applicable vscode docs](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide)
+
+## Usage Note
+
+We would love for the other graphql extension authors to freely use this syntax extension as well! Even if your extension is designed to replace `vscode-graphql`, or if it's designed for other other purposes. It uses an MIT license, but attribution is always a nice gesture to the original authors :)
+
+## License
+
+MIT License
+
+Copyright 2022 GraphQL Contributors
diff --git a/packages/vscode-graphql-syntax/package.json b/packages/vscode-graphql-syntax/package.json
index 2fe887c5dce..52d5eb1ef7f 100644
--- a/packages/vscode-graphql-syntax/package.json
+++ b/packages/vscode-graphql-syntax/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vscode-graphql-syntax",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "displayName": "GraphQL: Syntax Highlighting",
   "description": "Adds syntax highlighting support for .graphql & embedded support for javascript, typescript, vue, markdown, python, php, reason, ocaml and rescript",
   "publisher": "GraphQL",
@@ -115,9 +115,9 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/graphql/graphiql",
-    "directory": "packages/vscode-syntax"
+    "directory": "packages/vscode-graphql-syntax"
   },
-  "homepage": "https://github.com/graphql/graphiql/blob/main/packages/vscode-syntax/README.md",
+  "homepage": "https://github.com/graphql/graphiql/blob/main/packages/vscode-graphql-syntax/README.md",
   "scripts": {
     "vsce:package": "vsce package --yarn",
     "vsce:prepublish": "npm run vsce:package",