Added core typings and usage examples to social-urls and schema-org

Author: vikaspotluri123

packages/schema-org/README.md

@@ -11,6 +11,113 @@ or
 
 ## Usage
 
+```js
+const SchemaGenerator = require('@tryghost/schema-org');
+
+const schema = new SchemaGenerator();
+const makeSchemaTags = json => `<script type="application/ld+json">\n${json}\n</script>`;
+
+// Schema data pertaining to the entire site
+const site = {
+    title: 'Ghost',
+    url: 'https://demo.ghost.io',
+    image: {
+        url: 'https://static.ghost.org/v2.0.0/images/welcome-to-ghost.jpg',
+        // Optional!
+        dimensions: {
+            width: 1600,
+            height: 1050
+        }
+    }
+};
+
+// Example: generate schema for a post.
+// Other supported options are `author`, `tag`, and `home`
+const postObject = ghostPost(); // https://ghost.org/docs/api/v3/content/#posts
+
+// Schema data pertaining to this specific resource
+const postMeta = {
+    author: {
+        name: postObject.authors[0].name,
+        url: postObject.authors[0].url,
+        image: postObject.authors[0].profile_image,
+        description: postObject.authors[0].meta_description || postObject.authors[0].bio
+    },
+    meta: {
+        title: postObject.title,
+        url: postObject.url,
+        datePublished: postObject.published_at,
+        dateModified: postObject.updated_at,
+        image: postObject.feature_image,
+        keywords: postObject.tags.map(({name}) => name),
+        description: postObject.custom_excerpt || postObject.excerpt
+    }
+};
+
+// Logs a valid JSON-LD script
+console.log(
+    makeSchemaTags(schema.createSchema('post', {site, meta: postMeta}))
+);
+```
+
+### Supported Schemas:
+
+```typescript
+// type = 'author'
+interface AuthorSchemaProperties {
+    site: SiteData; // See `site` in the example
+    meta: {
+        name: string;
+        url: string;
+        description?: string;
+        sameAs?: string[]; // must be full URLs
+        image?: ImageObject; // see `site.image` in the example
+    }
+}
+
+// type = 'home'
+interface HomeSchemaProperties {
+    name: string;
+    site: SiteData;
+    meta: {
+        url: string;
+        description?: string;
+        image?: ImageObject;
+    }
+}
+
+// type = 'post'
+interface PostSchemaProperties {
+    site: SiteData;
+    author?: {
+        name: string;
+        url: string;
+        sameAs?: string[];
+        image?: ImageData;
+        description?: string;
+    };
+    meta: {
+        title: string;
+        url: string;
+        datePublished?: Date | string;
+        dateModified?: Date | string;
+        image?: ImageData;
+        keywords?: string[];
+        description?: string;
+    }
+}
+
+// type = 'tag'
+interface TagSchemaProperties {
+    site: SiteData;
+    meta: {
+        name: string;
+        url: string;
+        image?: ImageObject;
+        description?: string;
+    }
+}
+```
 
 ## Develop
 

packages/schema-org/SchemaGenerator.js

@@ -19,6 +19,80 @@ const trim = (schema) => {
     return schema;
 };
 
+/**
+ * @typedef {{
+ *  url?: string;
+ *  title?: string;
+ *  logo?: ImageObject
+ * }} SiteData
+ *
+ *
+ * @typedef {{
+ *  url: string;
+ *  dimensions?: {
+ *    width?: number;
+ *    height?: number;
+ *  }
+ * }} DimensionalImage
+ *
+ * @typedef {DimensionalImage | string} ImageObject
+ *
+ *
+ * @typedef {{
+ *   site: SiteData;
+ *   meta: {
+ *     name: string;
+ *     url: string;
+ *     description?: string;
+ *     sameAs?: string[];
+ *     image?: ImageObject;
+ *   }
+ * }} AuthorSchemaProperties
+ *
+ *
+ * @typedef {{
+ *   name: string;
+ *   site: SiteData;
+ *   meta: {
+ *     url: string;
+ *     description?: string;
+ *     image?: ImageObject;
+ *   }
+ * }} HomeSchemaProperties
+ *
+ *
+ * @typedef {{
+ *   site: SiteData;
+ *   author?: {
+ *     name: string;
+ *     url: string;
+ *     sameAs?: string[];
+ *     image?: ImageData;
+ *     description?: string;
+ *   }
+ *   meta: {
+ *     title: string;
+ *     url: string;
+ *     datePublished?: Date | string;
+ *     dateModified?: Date | string;
+ *     image?: ImageData;
+ *     keywords?: string[];
+ *     description?: string;
+ *   }
+ * }} PostSchemaProperties
+ *
+ *
+ * @typedef {{
+ *   site: SiteData;
+ *   meta: {
+ *     name: string;
+ *     url: string;
+ *     image?: ImageObject;
+ *     description?: string;
+ *   }
+ * }} TagSchemaProperties
+ */
+
 class SchemaGenerator {
     constructor(options) {
         this.options = options || {};
@@ -68,6 +142,10 @@ class SchemaGenerator {
         return trim(json);
     }
 
+    /**
+     * @param {'home' | 'author' | 'post' | 'tag'} type
+     * @param {HomeSchemaProperties | AuthorSchemaProperties | PostSchemaProperties | TagSchemaProperties} data
+     */
     createSchema(type, data) {
         if (!_.has(this.templates, type)) {
             type = 'home';

packages/social-urls/README.md

@@ -11,6 +11,14 @@ or
 
 ## Usage
 
+```js
+const {twitter: makeTwitter, facebook: makeFacebook} = require('@tryghost/social-urls');
+
+const socialUrls = [
+    makeTwitter('@ghost'), // https://twitter.com/ghost
+    makeFacebook('/ghost') // https://facebook.com/ghost
+];
+```
 
 ## Develop
 

packages/social-urls/lib/index.js

@@ -1,8 +1,16 @@
+/**
+ * @param {string} username
+ * @returns {string}
+ */
 module.exports.twitter = function twitter(username) {
     // Creates the canonical twitter URL without the '@'
     return 'https://twitter.com/' + username.replace(/^@/, '');
 };
 
+/**
+ * @param {string} username
+ * @returns {string}
+ */
 module.exports.facebook = function facebook(username) {
     // Handles a starting slash, this shouldn't happen, but just in case
     return 'https://www.facebook.com/' + username.replace(/^\//, '');