Merge remote-tracking branch 'origin/main' into dev

Author: NathanWalker

.github/workflows/ci.yml

@@ -2,13 +2,12 @@ name: Docs CI
 
 on:
   push:
-    branches: [ main, docs/ui ]
+    branches: [main, docs/ui]
   pull_request:
-    branches: [ main, docs/ui ]
+    branches: [main, docs/ui]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
@@ -19,7 +18,14 @@ jobs:
           node-version: 19
           cache: 'npm'
       - run: npm ci
-      - run: npm run lint:check --if-present
+      - run: npm run lint --if-present
       - run: npm run build --if-present
         env:
-          NODE_OPTIONS: "--max_old_space_size=4096"
+          NODE_OPTIONS: '--max_old_space_size=4096'
+# disabled because the output of textlint marks warnings as errors
+# # re-run lint:text with junit output for github annotations
+# - run: npm run lint:text -- --format junit --output-file lint-report.xml
+# - uses: mikepenz/action-junit-report@v3
+#   if: always()
+#   with:
+#     report_paths: 'lint-report.xml'

.textlintrc

@@ -0,0 +1,125 @@
+{
+  "rules": {
+    "terminology": {
+      "severity": "warning",
+      "defaultTerms": false,
+      // Some terms borrowed from https://github.com/cypress-io/cypress-documentation/blob/main/.textlintrc
+      "terms": [
+        // NativeScript specifics
+        ["absolute[- ]?layout(s?)", "AbsoluteLayout$1"],
+        ["dock[- ]?layout(s?)", "DockLayout$1"],
+        ["flex(?:box)?[- ]?layout(s?)", "FlexboxLayout$1"],
+        ["grid[- ]?layout(s?)", "GridLayout$1"],
+        ["root[- ]?layout(s?)", "RootLayout$1"],
+        ["stack[- ]?layout(s?)", "StackLayout$1"],
+        ["wrap[- ]?layout(s?)", "WrapLayout$1"],
+        ["activity[- ]?indicator(s?)", "ActivityIndicator$1"],
+        ["date[- ]?picker(s?)", "DatePicker$1"],
+        ["html[- ]?view(s?)", "HtmlView$1"],
+        ["list[- ]?picker(s?)", "ListPicker$1"],
+        ["list[- ]?view(s?)", "ListView$1"],
+        ["place[- ]?holder(s?)", "Placeholder$1"],
+        ["scroll[- ]?view(s?)", "ScrollView$1"],
+        ["search[- ]?bar(s?)", "SearchBar$1"],
+        ["segmented[- ]?bar(s?)", "SegmentedBar$1"],
+        ["tab[- ]?view(s?)", "TabView$1"],
+        ["text[- ]?field(s?)", "TextField$1"],
+        ["text[- ]?view(s?)", "TextView$1"],
+        ["time[- ]?picker(s?)", "TimePicker$1"],
+        ["web[- ]?view(s?)", "WebView$1"],
+        ["action[- ]?bar(s?)", "ActionBar$1"],
+
+        // Prefer simple
+        ["callback function", "callback"],
+
+        // Brands and Technologies
+        "JavaScript",
+        "TypeScript",
+        "NativeScript",
+        ["ns", "NativeScript"],
+        "GitHub",
+        ["VSCode", "VS Code"],
+        "webpack",
+        ["WebSocket(s?)", "WebSocket$1"],
+        "WiFi",
+        "API",
+        ["API['’]?s", "APIs"],
+        "CLI",
+        "CSS",
+
+        // Words and phrases
+        ["\\(s\\)he", "they"],
+        ["he or she", "they"],
+        ["he/she", "they"],
+        ["crazy", "complex"],
+        ["crazier", "more complex"],
+        ["craziest", "most complex"],
+        ["dumb", "unintended"],
+        ["insane", "outrageous"],
+        ["blacklist", "block"],
+        ["whitelist", "allow"],
+        ["will be executed", "will be called"],
+
+        // Prefer American spelling
+        ["behaviour", "behavior"],
+        ["cancelled", "canceled"],
+        ["cancelling", "canceling"],
+        ["centre", "center"],
+        ["colour", "color"],
+        ["customise", "customize"],
+        ["customisation", "customization"],
+        ["favourite", "favorite"],
+        ["labelled", "labeled"],
+        ["licence", "license"],
+        ["organise", "organize"],
+
+        // Common misspellings
+        ["gaurantee", "guarantee"],
+
+        // Words we would like to not use altogether
+        ["obviously", ""],
+        ["basically", ""],
+        ["simply", ""],
+        ["of( )?course", ""],
+        ["clearly", ""],
+        ["just", ""],
+        ["everyone knows", ""],
+        ["easy", ""],
+        ["which will( be)?", ""],
+        ["which is the", ""],
+
+        // Words we would like to not use at the start of a sentence
+        ["^so", ""],
+        ["^and", ""],
+        ["^but", ""],
+        ["^however", ""],
+
+        // Single word
+        ["change[- ]log(s?)", "changelog$1"],
+        ["code[- ]base(es?)", "codebase$1"],
+        ["e[- ]mail(s?)", "email$1"],
+        ["end[- ]point(s?)", "endpoint$1"],
+        ["file[- ]name(s?)", "filename$1"],
+        ["can[- ]not", "cannot$1"],
+        ["back-?end(s?)", "backend$1"],
+        ["front-?end(s?)", "frontend$1"],
+        ["full-?stack(s?)", "fullstack$1"],
+
+        // Multiple words
+        ["open-?source(ed?)", "open source$1"],
+
+        // Hyphenated
+        ["end ?to ?end", "end-to-end"],
+        ["retryability", "retry-ability"],
+        ["retriability", "retry-ability"],
+
+        // Shortened words
+        ["repo\\b", "repository"],
+        ["repos\\b", "repositories"]
+      ]
+    }
+  },
+  "filters": {
+    "comments": true
+  }
+}

.vitepress/config.mts

@@ -0,0 +1,82 @@
+import { defineConfig } from 'vitepress'
+import apiSidebar from '../content/api/sidebar.json'
+import mainSidebar from '../content/sidebar'
+import nav from './nav'
+import './theme/cliLanguage'
+import path from 'node:path'
+
+const isDev = process.env.NODE_ENV !== 'production'
+const branch = process.env.CF_PAGES_BRANCH ?? 'main'
+
+export default defineConfig({
+  srcDir: './content',
+  lang: 'en-US',
+  title: 'NativeScript',
+  description: 'NativeScript docs',
+  ignoreDeadLinks: true,
+  cleanUrls: true,
+  lastUpdated: true,
+  appearance: false,
+  themeConfig: {
+    editLink: {
+      ...(isDev && {
+        text: 'Edit in VS Code',
+      }),
+      // pattern:
+      //   'https://github.com/NativeScript/docs/blob/main/content/:filePath',
+      pattern: isDev
+        ? `vscode://file/${path.resolve(__dirname, '../content/:filePath')}`
+        : `https://pr.new/github.com/NativeScript/docs/edit/${branch}/content/:filePath?initialPath=:path`,
+    },
+    algolia: {
+      appId: '',
+      apiKey: '8d41b4ae92a02aea355e1dc8cfad1899',
+      indexName: 'nativescript',
+    },
+    nav,
+    sidebar: {
+      '/api': apiSidebar,
+      '/': mainSidebar,
+    },
+  },
+  markdown: {
+    headers: true,
+  },
+  async transformPageData(pageData, { siteConfig }) {
+    // const contributors = await githubAuthors.getAuthorsForFilePath(
+    //   path.resolve(siteConfig.srcDir, pageData.relativePath)
+    // )
+    // pageData.frontmatter.contributors ??= contributors ?? []
+
+    pageData.frontmatter.contributors = transformContributors(
+      pageData.frontmatter.contributors
+    )
+  },
+})
+
+function transformContributors(contributors?: string[] | false) {
+  // explicitly set to false to disable contributors list
+  if (contributors === false) {
+    return []
+  }
+
+  // if not set, default to NativeScript
+  if (!contributors) {
+    return [
+      {
+        username: 'NativeScript',
+        avatarURL: 'https://github.com/NativeScript.png?size=24',
+        profileURL: 'https://github.com/NativeScript',
+      },
+    ]
+  }
+
+  // otherwise, transform the list of usernames into a list of objects
+  return contributors.map((username: string) => {
+    return {
+      username,
+      avatarURL: `https://github.com/${username}.png?size=24`,
+      profileURL: `https://github.com/${username}`,
+    }
+  })
+}

.vitepress/config.ts

@@ -1,46 +1,53 @@
 export default [
-  ...(process.env.NODE_ENV !== "production"
+  ...(process.env.NODE_ENV !== 'production'
     ? [
         {
-          text: "[DEV] Reference",
-          link: "/dev-reference",
-          activeMatch: "^/dev-reference",
-          icon: "CodeBracketIcon",
+          text: '[DEV] Reference',
+          link: '/dev-reference',
+          activeMatch: '^/dev-reference',
+          icon: 'CodeBracketIcon',
         },
       ]
     : []),
   {
-    text: "Docs",
-    link: "/",
-    activeMatch: "^/(?!plugins|best-practices|api|dev-reference)",
-    icon: "AcademicCapIcon",
+    text: 'Docs',
+    link: '/',
+    activeMatch: '^/(?!plugins|best-practices|api|dev-reference|tutorials)',
+    icon: 'BookOpenIcon',
   },
   {
-    text: "Preview",
-    link: "/soon",
-    icon: "DevicePhoneMobileIcon",
+    text: 'Preview',
+    link: 'https://preview.nativescript.org',
+    icon: 'DevicePhoneMobileIcon',
+    target: '_blank',
   },
   {
-    text: "Plugins",
-    link: "/soon",
-    activeMatch: "^/plugins",
-    icon: "CubeTransparentIcon",
+    text: 'Tutorials',
+    link: '/tutorials/',
+    activeMatch: '^/tutorials',
+    icon: 'AcademicCapIcon',
   },
   {
-    text: "Best Practices",
-    link: "/soon",
-    activeMatch: "^/best-practices",
-    icon: "CheckIcon",
+    text: 'Plugins',
+    link: '/soon',
+    activeMatch: '^/plugins',
+    icon: 'CubeTransparentIcon',
   },
+  // {
+  //   text: 'Best Practices',
+  //   link: '/soon',
+  //   activeMatch: '^/best-practices',
+  //   icon: 'CheckIcon',
+  // },
   {
-    text: "Integrations",
-    link: "/soon",
-    icon: "CpuChipIcon",
+    text: 'Integrations',
+    link: '/soon',
+    icon: 'CpuChipIcon',
   },
   {
-    text: "API Reference",
-    link: "/api/",
-    activeMatch: "^/api",
-    icon: "CodeBracketIcon",
+    text: 'API Reference',
+    link: '/api/',
+    activeMatch: '^/api',
+    icon: 'CodeBracketIcon',
   },
-];
+]

.vitepress/nav.ts

@@ -0,0 +1,30 @@
+import { DefaultTheme } from 'vitepress';
+import { Theme } from 'vitepress';
+
+export declare type NSNavItem = DefaultTheme.NavItem & {
+    icon?: string;
+};
+
+export declare type NSSidebarGroup = DefaultTheme.SidebarItem & {
+    items?: NSSidebarItem[];
+};
+
+export declare type NSSidebarItem = DefaultTheme.SidebarItem & {
+    icon?: string;
+    hidden?: boolean;
+    visible?: boolean;
+    collapsible?: boolean;
+    hideChildren?: boolean;
+    type?: string;
+};
+
+export declare type NSThemeConfig = DefaultTheme.Config & {
+    mainURL?: string;
+    sidebar?: NSSidebarGroup[];
+    nav?: NSNavItem[];
+};
+
+declare const theme: (enhanceApp: Theme['enhanceApp']) => Theme;
+export default theme;
+
+export { }