feat(website): add site generation

.eslintrc.json

@@ -16,7 +16,8 @@
   ],
   "ignorePatterns": [
     "build/**/*.ts",
-    "**/*.js"
+    "**/*.js",
+    "website"
   ],
   "rules": {
     "no-prototype-builtins": 0,

.github/workflows/website.yml

@@ -0,0 +1,35 @@
+name: Build and publish website
+
+on:
+  push:
+    branches:
+      - "master"
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'yarn'
+
+      - name: Install library dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build library
+        run: yarn build
+
+      - name: Install website dependencies
+        run: yarn --cwd website install --frozen-lockfile
+
+      - name: Build website
+        run: yarn --cwd website build
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: website/build

tsconfig.json

@@ -11,5 +11,8 @@
     "skipLibCheck": true,
     "noErrorTruncation": true,
     "experimentalDecorators": true
-  }
+  },
+  "exclude": [
+    "website"
+  ]
 }

website/.gitignore

@@ -0,0 +1,23 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+
+/docs/api/

website/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/docs/examples/create-new-asn-structures-by-calling-constructors-with-parameters.example.ts

@@ -0,0 +1,11 @@
+import * as asn1js from 'asn1js';
+
+var sequence2 = new asn1js.Sequence({
+  value: [
+    new asn1js.Integer({ value: 1 }),
+    new asn1js.Integer({
+      isHexOnly: true,
+      valueHex: integer_data
+    }),
+  ]
+});

website/docs/examples/create-new-asn-structures-by-calling-constructors-with-parameters.mdx

@@ -0,0 +1,8 @@
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!./create-new-asn-structures-by-calling-constructors-with-parameters.example';
+
+# Create new ASN.1 structures by calling constructors with parameters
+
+<CodeBlock language="ts">
+  {source}
+</CodeBlock>

website/docs/examples/create-new-asn-structures.example.ts

@@ -0,0 +1,26 @@
+import * as asn1js from 'asn1js';
+
+var sequence = new asn1js.Sequence();
+sequence.valueBlock.value.push(new asn1js.Integer({ value: 1 }));
+
+var sequence_buffer = sequence.toBER(false); // Encode current sequence to BER (in ArrayBuffer)
+var current_size = sequence_buffer.byteLength;
+
+var integer_data = new ArrayBuffer(8);
+var integer_view = new Uint8Array(integer_data);
+integer_view[0] = 0x01;
+integer_view[1] = 0x01;
+integer_view[2] = 0x01;
+integer_view[3] = 0x01;
+integer_view[4] = 0x01;
+integer_view[5] = 0x01;
+integer_view[6] = 0x01;
+integer_view[7] = 0x01;
+
+sequence.valueBlock.value.push(new asn1js.Integer({
+  isHexOnly: true,
+  valueHex: integer_data,
+})); // Put too long for decoding Integer value
+
+sequence_buffer = sequence.toBER();
+current_size = sequence_buffer.byteLength;

website/docs/examples/create-new-asn-structures.mdx

@@ -0,0 +1,8 @@
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!./create-new-asn-structures.example';
+
+# Create new ASN.1 structures
+
+<CodeBlock language="ts">
+  {source}
+</CodeBlock>

website/docs/examples/use-internal-schemas-for-primitively-encoded-data-types.example.ts

@@ -0,0 +1,20 @@
+import * as asn1js from 'asn1js';
+
+var primitive_octetstring = new asn1js.OctetString({ valueHex: encoded_sequence }); // Create a primitively encoded OctetString where internal data is an encoded Sequence
+
+var asn1_schema_internal = new asn1js.OctetString({
+  name: "outer_block",
+  primitiveSchema: new asn1js.Sequence({
+    name: "block1",
+    value: [
+      new asn1js.Null({
+        name: "block2"
+      })
+    ]
+  })
+});
+
+var variant6 = org.pkijs.compareSchema(primitive_octetstring, primitive_octetstring, asn1_schema_internal);
+var variant6_verified = variant4.verified;
+var variant6_block1_tag_num = variant6.result.block1.idBlock.tagNumber;
+var variant6_block2_tag_num = variant6.result.block2.idBlock.tagNumber;

website/docs/examples/use-internal-schemas-for-primitively-encoded-data-types.mdx

@@ -0,0 +1,8 @@
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!./use-internal-schemas-for-primitively-encoded-data-types.example';
+
+# Use "internal schemas" for primitively encoded data types
+
+<CodeBlock language="ts">
+  {source}
+</CodeBlock>

website/docs/examples/validate-asn-against-pre-defined-schema.example.ts

@@ -0,0 +1,18 @@
+import * as asn1js from 'asn1js';
+
+var asn1_schema = new asn1js.Sequence({
+  name: "block1",
+  value: [
+    new asn1js.Null({
+      name: "block2"
+    }),
+    new asn1js.Integer({
+      name: "block3",
+      optional: true // This block is absent inside data, but it's "optional". Hence verification against the schema will be passed.
+    })
+  ]
+});
+
+var variant1 = org.pkijs.verifySchema(encoded_sequence, asn1_schema); // Verify schema together with decoding of raw data
+var variant1_verified = variant1.verified;
+var variant1_result = variant1.result; // Verified decoded data with all block names inside

website/docs/examples/validate-asn-against-pre-defined-schema.mdx

@@ -0,0 +1,8 @@
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!./validate-asn-against-pre-defined-schema.example';
+
+# Validate ASN.1 against pre-defined schema
+
+<CodeBlock language="ts">
+  {source}
+</CodeBlock>

website/docs/installation.md

@@ -0,0 +1,7 @@
+# Installation
+
+Run one of the following commands to add `asn1js` to your project:
+
+```bash npm2yarn
+npm install asn1js
+```

website/docusaurus.config.ts

@@ -0,0 +1,135 @@
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+import { themes as prismThemes } from 'prism-react-renderer';
+import packageJSON from '../package.json';
+
+const config: Config = {
+  title: 'asn1js',
+  tagline: 'asn1.js',
+  favicon: 'img/favicon.ico',
+  url: 'https://asn1js.org',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+  customFields: {
+    description: packageJSON.description,
+  },
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          path: 'docs',
+          sidebarPath: './sidebars.ts',
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+        blog: false,
+        // TODO: Add gtag trackingID.
+        // gtag: {
+        //   trackingID: '',
+        // },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  plugins: [
+    [
+      'docusaurus-plugin-typedoc',
+      {
+        entryPoints: ['../src/index.ts'],
+        tsconfig: '../tsconfig.json',
+        disableSources: true,
+        hideInPageTOC: true,
+        readme: 'none',
+      },
+    ],
+    'docusaurus-plugin-sass',
+  ],
+
+  themeConfig: {
+    prism: {
+      theme: prismThemes.oneDark,
+    },
+    image: 'img/card.png',
+    colorMode: {
+      defaultMode: 'light',
+      disableSwitch: true,
+      respectPrefersColorScheme: false,
+    },
+    navbar: {
+      style: 'dark',
+      logo: {
+        alt: 'asn1.js',
+        src: '/img/logo.svg',
+        width: 75,
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          position: 'right',
+          sidebarId: 'docs',
+          label: 'Docs',
+        },
+        {
+          type: 'docSidebar',
+          position: 'right',
+          sidebarId: 'examples',
+          label: 'Examples',
+        },
+        {
+          href: 'https://github.com/PeculiarVentures/ASN1.js',
+          position: 'right',
+          className: 'header-github-link',
+          'aria-label': 'GitHub repository',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      copyright: 'Made with ❤️ across the globe',
+      links: [
+        {
+          title: 'Learn',
+          items: [
+            {
+              label: 'Installation',
+              to: '/docs/installation',
+            },
+            {
+              label: 'Examples',
+              to: '/docs/examples/create-new-asn-structures-by-calling-constructors-with-parameters',
+            },
+            {
+              label: 'API',
+              to: '/docs/api/',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'GitHub',
+              href: 'https://github.com/PeculiarVentures/ASN1.js',
+            },
+            {
+              label: 'Contact us',
+              href: 'mailto:[email protected]',
+            }
+          ],
+        },
+        {
+          title: `Version: ${packageJSON.version}`,
+        },
+      ],
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;