diff --git a/documentation/docusaurus.config.js b/documentation/docusaurus.config.js index 7a07a24e..d2944a24 100644 --- a/documentation/docusaurus.config.js +++ b/documentation/docusaurus.config.js @@ -27,6 +27,10 @@ module.exports = { label: 'Tutorial', position: 'left', }, + { + type: 'localeDropdown', + position: 'right', + }, { href: 'https://github.com/lexiconhq/lexicon', label: 'GitHub', @@ -54,6 +58,20 @@ module.exports = { }, }, }, + i18n: { + defaultLocale: 'en', + locales: ['en', 'zh'], + path: 'i18n', + localeConfigs: { + en: { + label: 'English', + }, + zh: { + label: '中文', + path: 'zh', + }, + }, + }, plugins: ['docusaurus-plugin-image-zoom'], presets: [ [ diff --git a/documentation/i18n/zh/code.json b/documentation/i18n/zh/code.json new file mode 100644 index 00000000..58e4dfff --- /dev/null +++ b/documentation/i18n/zh/code.json @@ -0,0 +1,273 @@ +{ + "theme.ErrorPageContent.title": { + "message": "页面已崩溃。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.NotFound.title": { + "message": "找不到页面", + "description": "The title of the 404 page" + }, + "theme.NotFound.p1": { + "message": "我们找不到您要找的页面。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "请联系原始链接来源网站的所有者，并告知他们链接已损坏。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.admonition.note": { + "message": "备注", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "提示", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.danger": { + "message": "危险", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "信息", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "回到顶部", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "历史博文", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "历史博文", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "博文列表分页导航", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "较新的博文", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "较旧的博文", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "博文分页导航", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "较新一篇", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "较旧一篇", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "{count} 篇博文", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} 含有标签「{tagName}」", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "查看所有标签", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel": { + "message": "切换浅色/暗黑模式（当前为{mode}）", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "暗黑模式", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "浅色模式", + "description": "The name for the light color mode" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "页面路径", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription": { + "message": "{count} 个项目", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "文件选项卡", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "上一页", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "下一页", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "{count} 篇文档带有标签", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged}「{tagName}」", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "版本：{versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版尚未发行的文档。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版的文档，现已不再积极维护。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新的文档请参阅 {latestVersionLink} ({versionLabel})。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新版本", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "编辑此页", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "{heading}的直接链接", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "于 {date} ", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "由 {user} ", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最后{byUser}{atDate}更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "选择版本", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.tags.tagsListLabel": { + "message": "标签：", + "description": "The label alongside a tag list" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "关闭", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近博文导航", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.CodeBlock.copied": { + "message": "复制成功", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "复制代码到剪贴板", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "复制", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "切换自动换行", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.toggleCollapsedCategoryAriaLabel": { + "message": "打开/收起侧边栏菜单「{label}」", + "description": "The ARIA label to toggle the collapsible sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "主导航", + "description": "The ARIA label for the main navigation" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "选择语言", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "本页总览", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "阅读更多", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "阅读 {title} 的全文", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "阅读需 {readingTime} 分钟", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.breadcrumbs.home": { + "message": "主页面", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "文档侧边栏", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "关闭导航栏", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← 回到主菜单", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "切换导航栏", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "重试", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "跳到主要内容", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "标签", + "description": "The title of the tag list page" + } +} diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0.json b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0.json new file mode 100644 index 00000000..ff781622 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0.json @@ -0,0 +1,38 @@ +{ + "version.label": { + "message": "1.0.0", + "description": "The label for version 1.0.0" + }, + "sidebar.docs.category.Lexicon": { + "message": "Lexicon", + "description": "The label for category Lexicon in sidebar docs" + }, + "sidebar.docs.category.Getting Started": { + "message": "Getting Started", + "description": "The label for category Getting Started in sidebar docs" + }, + "sidebar.docs.category.Configuring the Mobile App": { + "message": "Configuring the Mobile App", + "description": "The label for category Configuring the Mobile App in sidebar docs" + }, + "sidebar.docs.category.White Labeling": { + "message": "White Labeling", + "description": "The label for category White Labeling in sidebar docs" + }, + "sidebar.docs.category.Deploying Prose": { + "message": "Deploying Prose", + "description": "The label for category Deploying Prose in sidebar docs" + }, + "sidebar.docs.category.Configuring Discourse": { + "message": "Configuring Discourse", + "description": "The label for category Configuring Discourse in sidebar docs" + }, + "sidebar.docs.category.Publishing your App": { + "message": "Publishing your App", + "description": "The label for category Publishing your App in sidebar docs" + }, + "sidebar.tutorial.category.Tutorial": { + "message": "Tutorial", + "description": "The label for category Tutorial in sidebar tutorial" + } +} diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/app-store.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/app-store.md new file mode 100644 index 00000000..941750d5 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/app-store.md @@ -0,0 +1,276 @@ +--- +title: Publishing to the App Store +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +At this point, you've at least made some minor adjustments to the Lexicon Mobile App, and are ready to publish it so that your users can download it. + +In this page, we'll cover the process of publishing it on iOS. + +## Prerequisites + +- An Apple Developer account +- An Expo account +- XCode is installed on your development machine +- EAS CLI 2.6.0 or newer + +To get started with TestFlight and publishing your app, you'll need an **Apple Developer account**. + +This will enable you to interact with Apple as you go through the process of submitting to TestFlight and, eventually, the App Store. + +You'll also need an [Expo account](https://expo.dev/signup) so you can build your app, download it, and upload it to Apple's servers. + +Finally, you'll want to have already downloaded and installed [Xcode](https://developer.apple.com/xcode/), which is what you'll use to upload your built app to Apple's servers. + +:::note +If you don't yet have an account with Apple, you'll need to enroll in the [Apple Developer Program](https://developer.apple.com/programs/enroll/) first. Note that there is an annual cost associated with this. + +Additionally, you'll want to make sure you have an account with [Expo](https://expo.dev/signup) so you can use features like [EAS Submit](https://docs.expo.dev/submit/introduction/). +::: + +## Register a new Bundle ID + +Each app in Apple's App Store has a unique **Bundle Identifier**, or Bundle ID. + +In order to publish the app anywhere, including to TestFlight, you'll need to have a Bundle ID registered for your app with Apple. + +Typically, this uses the format of `com..`. + +For example, if your company is named Expo, and your app is named Expo Go, your Bundle ID could be: + +``` +com.expo.expogo +``` + +You can follow these instructions to get one. + +- Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/bundleId/add/bundle). +- Fill in the following fields, and then click `Continue` + Regsiter App + + - **Description**: You can insert the app name as its description. + + - **Bundle ID**: Select `Explicit`, and then insert then insert your bundle ID in the input field. + +- Capabilities + + - You can leave this section empty. + +## Add a New App in App Store Connect + +Steps: + +- Sign in to your [App Store Connect](https://appstoreconnect.apple.com/) account. +- Click on `My Apps`. + App Connect +- Click on the `+` button to add new app. + Add New App +- Fill out the requested information about your app, and then click `Create`. + Add New App + + - **Platforms**: Select `iOS`. + - **Name**: The name of your app, as it will appear on the App Store and user's devices. + - **Primary Language**: The primary language that will be used if localized app information is not available. + - **Bundle ID**: Choose the Bundle ID you created above. + - **Note**: double-check that it's correct, because you can not change it afterwards. + - **SKU (Stock Keeping Unit)**: A unique ID to differentiate your app from the others, similar to a product ID. + - **User Access**: Full access means all users will have access to the app, while limited access means that the app can only be accessed by certain roles defined within App Store Connect. + +## Configuration + +After creating the app in App Store Connect, you'll want to jump back over to the codebase and make some adjustments. + +### Build Config + +:::note +If you haven't yet installed the EAS CLI, follow the instructions in the [tutorial](tutorial/setup#install-the-eas-cli). +::: + +First, you'll need to ensure you've set your app name and slug in `frontend/app.json`. The [slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) is used as part of the URL for your app on Expo's web services, so it is recommended to use kebab-case (e.g., `my-lexicon-app`). + +Replace these placeholders with your desired values: + +```json + "name": "", + "slug": "", +``` + +Next, configure EAS Build by running this command from the `frontend/` directory: + +```bash +eas build:configure +``` + +The EAS CLI will prompt you to specify `android.package` and `ios.bundleIdentifier` if those values are not already provided in `app.json`. You'll want to add the bundle ID you just registered in App Store Connect as the `bundleIdentifier`. + +Then you can see that the value has been updated in the `ios` section of `frontend/app.json` file. + +```json + "ios": { + "supportsTablet": false, + "buildNumber": "1.0.0", + "bundleIdentifier": "", + "config": { + "usesNonExemptEncryption" : false + } + }, +``` + +:::note +We set `usesNonExemptEncryption` to `false` because Lexicon doesn't leverage that feature. + +For further details, please take a look at [this link](https://developer.apple.com/documentation/bundleresources/information_property_list/itsappusesnonexemptencryption) from Apple's documentation. +::: + +### Setup Config Values + +:::info +When publishing your app, it is necessary to deploy Prose somewhere publicly accessible, perhaps on a cloud hosting provider like AWS or DigitalOcean. If Prose is only running on your local machine, users that download your app won't be able to use it. +Check [the documentation](deployment) to deploy Prose if you haven't already. +::: + +Next, configure the **Prose URL** for your build in `Config.ts`. You can set a different URL for each build channel. + +:::note +In the original release of Lexicon, the **Prose URL** was specified in `frontend/.env`. However, as part of migrating to Expo's EAS feature, we centralized the configuration into `frontend/Config.ts` to save you the trouble of needing to maintain it in more than one place, as suggested in the [Expo documentation](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update) +::: + +```ts +const config = { + // ... + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, +}; +``` + +### Setup Apple Dveloper Account + +Lastly, please adjust these fields in `eas.json` with your account information to submit the app: + +```json + "base": { + "ios": { + "appleId": "", + "ascAppId": "", + "appleTeamId": "" + }, + ... + }, +``` + +- **appleId**: your apple ID (e.g., `john@gmail.com`). +- **ascAppId**: your App Store Connect app ID. Find your ascAppID by following [this guide](https://github.com/expo/fyi/blob/main/asc-app-id.md) (e.g., `1234567890`). +- **appleTeamId**: You can check your apple team ID [here](https://developer.apple.com/account/) (e.g., `12LE34XI45`). + +## Build your App for iOS + +Before publishing, you'll need to build your app by instructing Expo to generate an iOS build. + +It is recommended to build your app with the `preview` profile before releasing to verify that it works as expected. See [this tutorial](tutorial/building) to learn more about build profiles. + +Run this command: + +```bash +eas build --platform ios --profile preview +``` + +When you run the above command, Expo will prompt you for your Apple ID and password. + +Once the above step has been completed, login to your account on [Expo](https://expo.dev) and download your newly built app. + +Navigate to your project in the [Expo web console](https://expo.dev), then click on the **Builds** menu located on the left-hand side of the screen. + +- Click on the project you want to install. + Builds + +- Download the iOS build by pressing the `Download` button in the `Build Artifact` section. + Build Artifact + +This will download a tar file containing your app. Extract the file, then drag it to your simulator to install it. See [this section](tutorial/building#1-preview) of the tutorial to learn about running the app on real devices. + +Once you have verified that the app runs as expected, you can proceed to build it for release: + +```bash +eas build --platform ios --profile production +``` + +The approach for a production build is similar to the one used for generating a preview build. However, unlike a preview build, you won't be able to launch the production build in the iOS simulator—it is intended solely for publishing to the App Store. + +Once this process is completed, you can proceed with submitting it to Apple. This process typically involves Apple's TestFlight service. + +## Submit to TestFlight + +TestFlight is a key aspect of Apple's Developer Program, which enables developers to provide beta users with access to their app under less restrictive review requirements. + +With TestFlight, you're able to invite users to test your app and collect their feedback before releasing it to the public on the App Store. You can learn more about TestFlight [here](https://developer.apple.com/testflight/). + +Submitting an iOS app is much easier with EAS Submit. This is covered in more detail in the [tutorial](tutorial/publishing). + +Run the following command to start publishing the app to TestFlight: + +```bash +eas submit --platform ios --profile production +``` + +Once the process has completed successfully, we can check the build in App Store Connect. + +In App Store Connect, click on the TestFlight Tab. + +You'll see the [status](https://help.apple.com/app-store-connect/#/dev3d6869aff) of your built version. + +- **Red** indicates that you need to perform some action. +- **Yellow** indicates that some aspect of the process is pending—either from you, or from Apple. +- **Green** indicates that the build is being tested in TestFlight, or is ready to be submitted for review. + +You won't be able to begin beta testing with TestFlight until an official tester from Apple verifies your app. + +In order to allow Apple to properly test your Lexicon-powered app, they'll need to have credentials to login your Discourse site. + +Before submitting your app, you'll need to create those credentials in Discourse and specify them in App Store Connect. + +- In App Store Connect, click on your app. +- Click on TestFlight App. +- Click on Test Information in the sidebar on the left-hand side. +- Fill the required fields, then check the `Sign in required` checkbox, and enter the credentials. + Review Information Sign In +- Please also provide information for a person to contact if the review team needs additional information. + Review Information Contact + +### Specify Users for Beta Testing + +Beta Test Users can belong to an Internal Group or an External Group. + +You can specify internal users by going to the Internal Group section, and clicking on **App Store Connect Users**. + +Similarly, you can specify external users by selecting External Groups, and clicking on **Add External Testers**. + +#### More Information + +TestFlight and App Store Connect are sophisticated tools to help with the process of submitting, testing, and publishing your app. + +If you have further questions or just want to learn more, we'd recommend that you make use of Apple's documentation, which is very high quality. + +For more information about TestFlight in general, read the [documentation](https://developer.apple.com/testflight/). + +Similarly, for specific information about beta testing with TestFlight, check out [Testing Apps with TestFlight](https://testflight.apple.com/). + +## Publish to the App Store + +Once you've successfully passed Apple's review process and have received enough feedback from your beta testers, you're ready to publish to the App Store and go live! :tada: + +As a few final reminders, double-check that... + +- Your Discourse instance is online, reachable, and functioning correctly. +- The built version of your app is configured to point at the correct Prose server. +- Your Prose server is online, reachable and healthy. +- Your Prose server is deployed with the [recommended guidlines](dedicated#configure--deploy-prose) for production. + - In particular, ensure that its traffic is encrypted using an SSL certificate. + +Next, we'll guide you through the process of publishing your app for Android devices on the Google Play Store. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/assets.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/assets.md new file mode 100644 index 00000000..a24dcad0 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/assets.md @@ -0,0 +1,47 @@ +--- +title: App Icon & Other Assets +--- + +The Lexicon Mobile App contains multiple assets that can be replaced in order to White Label it. + +The assets that can be modified are as follows: + +## App Logo + +Used to show the app logo in the application, such as on the Login, Register, and 2FA Scenes. + +The assets are located at `frontend/assets/images/logo.png` and `frontend/assets/images/logoDark.png`. The `logo.png` is used in light color scheme and `logoDark.png` is used in dark color scheme. To customize it, simply replace the existing file with your own `logo.png` and `logoDark.png`. + +## Favicon + +Used to show the app logo. + +The asset is located at `frontend/assets/favicon.png`. To customize it, simply replace the existing file with your own `favicon.png`. + +## Image Placeholder + +Used to temporarily take an image place when it is loading. + +The asset is located at `frontend/assets/images/imagePlaceholder.png`. To customize it, simply replace the existing file with your own `imagePlaceholder.png`. + +## Icons + +Used to display icons inside the application. + +The assets are located in the `frontend/assets/icons` folder. If you want to add more or edit the remaining icons, you need to insert the icons to the `frontend/assets/icons/` folder and import them in `frontend/src/icons.ts`. + +There are some standards applied to the icons, such as: + +#### Uniform Icon Size to Maintain Visual Consistency + +The UI is designed around the default base dimensions of 28x28px for icons. + +If you adjust this, you may need to modify other aspects of the theme or fonts in order to maintain a clean appearance. + +Similarly, if you provide a new icon that does not conform to these dimensions, you may run into visual inconsistencies. + +#### SVG Icons have their Fill Color Controlled via `currentColor` + +If you are adding a new icon that you expect to interact with theme's colors, ensure that its color is not hard-coded, and is instead set to `currentColor`. + +If you are unfamiliar with this concept, take a look at the [MDN Specification on SVG color values](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/color). diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/commercial-support.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/commercial-support.md new file mode 100644 index 00000000..9d164810 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/commercial-support.md @@ -0,0 +1,9 @@ +--- +title: Commercial Support +--- + +With official support, you get expert help straight from the core team. We provide app customization, dedicated support, prioritize feature requests, deployment strategies, advice on best practices, design decisions, and team augmentation. + +Additionally, we are open to engagements for non-technical site owners looking to customize, deploy, and launch a mobile app for their Discourse users. + +Reach out to us for consulting at support@kodefox.com. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/concepts.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/concepts.md new file mode 100644 index 00000000..f32b0652 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/concepts.md @@ -0,0 +1,63 @@ +--- +title: Concepts and Architecture +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Prose: Discourse through GraphQL + +It is worth acknowledging upfront that Discourse already provides a traditional, RESTful API for developers out of the box. + +However, [the official documentation](https://docs.discourse.org/) for this API points out that it is incomplete, effectively serving as a starting point. + +> Note: For any endpoints not listed you can follow the reverse engineer the Discourse API guide to figure out how to use an API endpoint. +> +> —**Discourse API Documentation** + +The core team, as well as members of the [support forum](https://meta.discourse.org), regularly respond to questions about the API by [encouraging developers to reverse-engineer the API](https://meta.discourse.org/t/how-to-reverse-engineer-the-discourse-api/20576). As of this writing, the topic for how to reverse engineer the API has been linked to from nearly 200 other topics on the support forum. + +To help you simplify the process for you, Prose strives to normalize a subset of the API. We have done so with the hope that it will save you some time as you develop against Discourse. + +#### GraphiQL + +Prose's GraphQL implementation includes an [in-browser GraphQL IDE](https://www.graphql-yoga.com/docs/features/graphiql), known as [GraphiQL](https://github.com/graphql/graphiql), which allows developers to easily reference the entire documentation and schema and make queries against a running Discourse instance. + + + +This means you can rapidly get a clear understanding of how a method behaves—and what parameters it requires—without digging through support posts or reverse-engineering the REST API. + +#### Why GraphQL? + +There is no shortage of articles about both the [benefits](https://www.howtographql.com/basics/1-graphql-is-the-better-rest) and [tradeoffs](https://lwhorton.github.io/2019/08/24/graphql-tradeoffs.html) of GraphQL. + +We're well aware that GraphQL isn't some magical solution that solves all the problems of other API paradigms. + +Having said that, we chose to build Lexicon with it for two primary reasons. + +1. Our team is familiar and fluent with GraphQL, and deeply enjoys working with it. + +2. The tooling, libraries, and auto-generated documentation provide out-of-the box benefits which we can pass onto others with no additional effort. + +#### Why Expo? + +[Expo](https://docs.expo.io/) is both a framework and a platform for building universal React applications. In particular, it provides a superior development experience when building mobile apps with React Native. + +We find that Expo makes us much more effective as developers, and also provides excellent services to facilitate the entire process of building and publishing React Native apps. + +## Lexicon Architecture + +The Lexicon Stack is fairly simple, and only consists of 3 major pieces: + +- The Lexicon Mobile App +- The Prose GraphQL API +- A running, accessible Discourse instance + +Below is a diagram illustrating the typical architecture for a Lexicon-powered mobile app. + +IOS Lexicon Login Page + +As indicated above, the mobile app makes requests to a deployed Prose GraphQL server. + +The Prose server has been configured to point at an active Discourse instance of the developer's choice. + +Traffic then flows back from Discourse, through Prose, and returns to the mobile app over a GraphQL interface. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/contributing.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/contributing.md new file mode 100644 index 00000000..0fe6fbe9 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/contributing.md @@ -0,0 +1,131 @@ +--- +title: Contributing +--- + +Thank you for your interest in contributing! :sparkles: + +We greatly appreciate the time and effort you're willing to put forth to make Lexicon even better. + +There are several ways to help out. + +## Reporting Bugs + +The best way to let us know about a bug is by [creating a new issue](https://github.com/lexiconhq/lexicon/issues/new) on [Github](https://github.com/lexiconhq/lexicon). + +As always, we recommend searching the existing open and closed issues before opening a new one. + +When you create the issue, please be sure to include the following: + +- A detailed description of the bug and its behavior + +- The behavior you expected instead of the bug + +- A list of steps for how to reproduce the bug + +- Details about the device(s) and version(s) you're observing the bug on + +- Screenshots and screen recordings, while not necessary, are very welcome! + +Once we've received your bug report, we will triage it and label it accordingly. + +## Contribute to the Project + +Want the honor of being listed in our contributors section :clap:? + +We'd love to get a PR from you addressing an existing issue, adding a feature, or even just improving the documentation. + +To get started contributing, follow the instructions below. + +### Instructions + +**1. Fork the [official Lexicon repository](https://github.com/lexiconhq/lexicon)** + +You probably already know the drill - click on **Fork** button on the upper-right corner. + +**2. Clone your Fork of Lexicon** + +Be sure to clone **_your_** fork to your development machine (as opposed to cloning the main Lexicon repository). + +``` +$ git clone https://github.com/YOUR_USERNAME/lexicon.git +``` + +If you need further guidance with cloning, head over to our [Quick Start](quick-start#installation) section. + +Just bear in mind that the Quick Start section walks you through cloning the Lexicon repository. So make sure you change the URL to your username as referenced above. + +**3. Run and connect the app with Prose and a Discourse Host** + +For a comprehensive walk-through of this step, follow the instructions in the [**Setup**](setup#discourse-host) section. + +If you already have a deployed Prose instance that is pointing at a Discourse instance, you can simply configure the Lexicon Mobile App to point at the address of your Prose deployment. + +However, if you don't have that, or if you're planning on making adjustments to the Prose server itself, you'll want to ensure the Lexicon Mobile App is configured to point at a Prose server that you have running locally. + +**4. Get Started with your Contribution** + +At this point, you should be setup to dig in on the main work of your feature, bugfix, or other contribution. + +Remember that it's necessary to have the [**ESLint**](https://eslint.org/docs/user-guide/getting-started) and [**Prettier**](https://prettier.io/) plugins installed in your IDE, as those are required in order for the Pull Request checks to pass. + +We would recommend working in [VSCode](https://code.visualstudio.com/), since that is what we used to develop Lexicon. However, it is up to you, you only need to ensure that ESLint and Prettier are functioning properly within your IDE. + +**5. Run the Test Suite** + +Follow these [**steps**](setup#run-the-test-suite) to run the Lexicon test suite. + +In order to speed up the feedback cycle, it is recommended that you ensure that all tests are passing locally before pushing, especially if you already have an open PR. + +This is primarily because we have configured our Github project to block PRs from being merged if any of the build steps fail. + +If the reviewers see that tests are failing, they aren't able to review it as quickly, and will likely request that you resolve any build issues before requesting review again. + +**6. Stage, Commit, and Push your Local Changes** + +If you're unfamiliar with this process, please take a look at this [great article](https://github.com/git-guides/#learning--mastering-git-commands) from Github to bring you up to speed. + +**7. Create a New Pull Request** + +Your code is ready to submit! :tada: + +Go to the Lexicon [Pull Requests tab](https://github.com/lexiconhq/lexicon/pulls), and compare the changes between your branch and the master branch. + +Double-check and make sure you didn't push anything you don't want included in your PR. + +Then, go ahead and create a new Pull Request from your forked repository. + +Please be sure to follow the Pull Request template, add related labels, and please mention the issue you are addressing to help us keep track of what's being worked on. + +## Share Your Thoughts with Us + +We'd love to hear your new ideas! Drop them in the [Issues tab](https://github.com/lexiconhq/lexicon/issues). + +## Spread the Word + +Let others know about your awesome experience using Lexicon on social media, and tag us on Twitter [@GetLexicon](https://twitter.com/GetLexicon). + +And if you build your app using Lexicon, please let us know. We'd love to help you spread the word about what you've built! + +## Improve the Documentation + +As a closing thought, if you find any issues with the Lexicon documentation, or just think you could make it better, you can get started with these brief instructions below. + +To generate and run the documentation locally, from the project root, run: + +```sh +npm run docs:start +``` + +Similarly, you can build the documentation using: + +```sh +npm run docs:build +``` + +All documentation is in the `documentation/` directory, and the Markdown pages used to generate this site are under `documentation/docs`. + +If you end up making a PR to improve the documentation, please be sure to label your PR with the `Documentation` label. + +:::note +Don't hesitate to ask if you have any further questions. We're always happy to help. :smile: +::: diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/customize.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/customize.md new file mode 100644 index 00000000..6797d756 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/customize.md @@ -0,0 +1,28 @@ +--- +title: Customization +--- + +## Theming + +As part of its [White Labeling Support](white-labeling), Lexicon allows you to customize the theme of the mobile app. +You can configure the base and functional colors according to a color scheme of your choosing. +You're also able to customize icons, fonts, and even the error messages that appear inside of the mobile app. +To get started with this, check out the [Theming page](theming) under the [White Labeling](white-labeling) section. + +## White Labeling the Mobile App Assets + +To provide your users with a unique experience that matches your brand, you can customize the splash screen and app icon on their device. + +This will replace all Lexicon branding with your own. + +Further details can be found in both the [Tutorial](tutorial/white-label) and the [White Labeling Section](white-labeling) of this documentation. + +## Enabling Additional Discourse features + +As you might already be aware, Discourse is a highly customizable piece of software. Much of it is customizable from the Admin Site Settings page on your Discourse instance. + +Some of these settings will translate automatically into the Lexicon Mobile App, such as `authorized extensions`. + +In general, we have done our best to get out of the way and use Discourse as the source of truth for how the Lexicon Mobile App should appear and behave. + +If you find any settings that Lexicon is not responding to, but you feel it should, please open an issue and let us know. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/dedicated.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/dedicated.md new file mode 100644 index 00000000..75fe8afe --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/dedicated.md @@ -0,0 +1,300 @@ +--- +title: Hosting & Configuration +--- + +As mentioned in the [Overview](deployment), this section is meant to guide you through configuring and deploying Prose on a dedicated instance. + +## Decide on Where to Host + +First, you'll need to answer the following question. Where would you like to host Prose? + +While there are many options that vary by project and developer preferences, the simplest way is often to use a cloud provider of your choice. + +In the [Lexicon tutorial](tutorial/setup-cloud-server), we walk you through this process using Digital Ocean. + +If you're confused about this step, or don't have a preference, you should take some time to work through it. + +However, if you already know what you're doing, feel free to use any cloud provider or hosting solution of your choice. + +### Hosting Checklist + +Once you've decided on a host, go through the checklist below to verify that everything is setup as expected. + +#### ✅ Ensure Access & Permissions on the Host + +At a minimum, you will need to be able to login to the host. Some cloud providers offer a virtual, web-based terminal, but ideally you can get credentials to login directly. + +If your host is in a UNIX-based environment, you should also have permissions to run commands as `sudo`. + +A quick way to check this is to simply attempt to run a command with `sudo`: + +```sh +$ sudo ls +``` + +However, if you have a restrictive hosting environment, you will just need a way to place the Lexicon source onto the host, install its dependencies, and expose it on a port. + +Bear in mind that a restrictive hosting environment is not ideal, especially since the recommended setup makes use of Docker. + +#### ✅ Ensure the Host is reachable in the way you need it + +Typically, this means that your host is accessible on the open internet. + +However, you might have different constraints, such as only needing the host to be accessible from within a VPN or a local network. + +
+ +Once you have setup a host which is reachable in the way you need it to be, you can begin configuring Prose on it. + +## Configure & Deploy Prose + +### Without Docker + +Naturally, setting up Prose without Docker involves more manual steps and can be platform-specific. + +We have already covered this approach well in the tutorial. In particular, you can dig in with it on the page, [Setup the Prose GraphQL API](tutorial/install-prose#install-manually) + +### With Docker + +The Prose Docker image comes preconfigured to run Prose using **[PM2](https://pm2.keymetrics.io/)**, which is a sophisticated toolset for running Node processes in production. + +This is typically a reasonable setup, with which you can even expose the PM2 server directly to requests on the host. + +However, if you'd prefer a different setup, perhaps using Nginx as a reverse proxy to the Docker container, feel free to modify the Dockerfile to match your requirements. + +#### Install Docker + +**[Docker](https://www.docker.com/)** is a containerization framework that makes it easy to build, manage, and deploy your application stack in a way that is safer, more reliable, and reproducible across multiple platforms. + +There are countless guides available for installing Docker on a given operating system. + +Ubuntu is one of the more common operating systems avaiable through most cloud providers. + +Docker provides a [full tutorial](https://docs.docker.com/engine/install/ubuntu/) for this, and even provides a convenience script that you can run in two lines: + +```sh +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh +``` + +Whichever path you need to take, just make sure that Docker is up and running on your host before continuing. + +#### Configure Environment Variables + +A comprehensive list of all Prose environment variables can be found on the [Environment Variables](env-prose) page. + +In brief, at a minimum, you'll want to ensure that `PROSE_DISCOURSE_HOST` is set. + +Another variable to pay attention to is `PROSE_APP_PORT`. This defaults to port 80, which instructs Prose to listen on that port. + +Depending on your setup, you might want it to listen on a different port. + +
+ +#### Build Prose from the Dockerfile + +If you'd like to use Docker to manually build Prose, run the following command from the **project root**. + +This might be of interest to you if you'd like to make some adjustments to the Dockerfile itself. + +Alternatively, if you simply wish to pull the latest Prose build from Docker Hub, you can [skip to the next step](#pulling-the-prose-docker-image). + +Unless you've made modifications to the Dockerfile and have it stored elsewhere, you can get started building by running: + +```bash +docker build -t prose:latest -f api/deploy/Dockerfile api/ +``` + +The command searches for the `Dockerfile` at `api/deploy/Dockerfile` because we instructed it to look there with the `-f` flag. + +Then, it uses `api/` as the context for the build, which allows the references in the `Dockerfile` to resolve correctly. + +By passing the `-t prose:latest` tag, it tags the locally built image as the latest build. This can be useful for identifying and managing the images in a Docker environment over time. + +#### Pull the Prose Docker Image + +If you'd rather just use the latest release of the Prose image, you can simply run: + +``` +docker pull kodefox/prose:latest +``` + +#### Run the Prose Docker Container + +Next, to run the newly built image, run the following command: + +```bash +docker run -d \ + -e PROSE_DISCOURSE_HOST=https://discourse.example.com \ + -e PROSE_APP_PORT=4000 \ + --name prose \ + -p 5000:4000 \ + kodefox/prose:latest +``` + +:::note +If you built the image by hand, you'll want to substitute `kodefox/prose:latest` with the image name and tag you used, such as `prose:latest`. +::: + +To recap, let's briefly break down that command line-by-line + +**Run in Detached Mode** + +```bash +docker run -d +``` + +The first line lets Docker know to run the container in **detached mode**. + +This means that the command will run in the background, will not be tied to your current session, and will keep running even if you log out. + +If you omitted the `-d` flag, Docker would run the container in the foreground, and exiting the process in the foreground would stop the container. + +**Set Environment Variables** + +```bash +-e PROSE_DISCOURSE_HOST=https://discourse.example.com +-e PROSE_APP_PORT=4000 +``` + +These lines instruct Docker to pass the environment variables of `PROSE_DISCOURSE_HOST` and `PROSE_APP_PORT` to the container when running it. + +These are both application-level environment variables that Prose itself will leverage to run properly. + +The Docker image expects these values to be set and passes them to the container's environment, which Prose then accesses via `process.env`. + +**Name the Container** + +```bash +--name prose +``` + +This line tells Docker to give the running container a name. This makes it easier to identify and interact with via commands, such as: + +```bash +docker stop prose +``` + +**Configure a Port Mapping between the Host and the Container** + +```bash +-p 5000:4000 +``` + +Next, we configure Docker with a port mapping, which tells Docker to listen to map the host port of `5000` to the container port of `4000`. + +Because we previously set `PROSE_APP_PORT=4000`, this means that all requests to the host at port `5000` will be forwarded to Prose inside of its container on port `4000`. + +```bash +kodefox/prose:latest +``` + +The last line of the command tells Docker which image to use for the container. + +Above, if you built the Prose image by hand, it was tagged as `prose:latest`. + +If you chose to pull from Docker Hub, this is simply instructing Docker to pull that image if necessary, and then start the container with it. + +#### Next Steps + +At this point, you should have a Docker container running the Prose server on your host. + +However, in terms of preparing your Prose host for production, you aren't quite there yet. + +Below, we'll guide you through the last steps, finalizing your deployment of the Prose GraphQL Server. + +#### Setup SSL (IMPORTANT) + +:::danger +Deploying Prose without SSL in a way that is publicly accessible is **extremely risky**. + +Doing so could provide an attacker with full access to your Discourse site and all of its data. +::: + +The **most important next-step** to take at this point is to configure an SSL certificate for your Prose host. + +The reason this is so important is that, without SSL, Prose's traffic between your users' devices and Discourse is not encrypted. + +And this means that attackers can snoop on your users' requests to Prose and Discourse—including, importantly, their authentication information. + +To put it bluntly, deploying Prose without configuring SSL is irresponsible and compromises the security of your Discourse instance. + +An attacker could even steal your authentication token and use it to access, and potentially destroy, your Discourse site. + +##### How to Setup SSL + +There are a variety of methods to obtain SSL certificates. Some are free, and some are paid. + +The free route involves using [Let's Encrypt](https://letsencrypt.org/), which is very useful, but can require more technical knowledge to setup correctly—depending on your configuration. A key difference is that you need to renew the certificates more frequently. + +The paid route involves using a provider like [DigiCert](https://www.digicert.com/) to obtain certificates that take longer to expire. + +Either way, you'll end up with certificate files that you can configure and launch your webserver with. + +Ideally, at this point, you've already purchased a domain. If you haven't, we'd recommend using a domain provider to get a low-cost domain name. + +You could host Prose at a subdomain of your existing Discourse site, like `prose.mydiscoursesite.com`. + +Or, you could just get a cheap, nonsense domain, like `purplemonkeydishwasher.tech`—since your users won't typically see it anyway. + +Regardless, to emphasize it again, it is **critical** that you don't deploy Prose into production until you have prepared your host to encrypt the traffic from Prose. + +#### Determine how you'll expose Prose on the host + +When someone navigates to your host which is running Prose, how will their request get routed to Prose? + +If you had exposed Prose directly on port 80—NOT recommended—and your host's domain name was `myproseserver.com`, then a user would navigate to `http://myproseserver.com` and be greeted with the [GraphiQL interface](https://www.graphql-yoga.com/docs/features/graphiql). + +However, a more common approach is to use a dedicated webserver, such as Nginx or Apache, that acts as a reverse-proxy. + +With this approach, the websever listens for all requests on the ports you tell it to, and is configured to route traffic to Prose, which is listening on a non-privileged port, like 8080. + +We recommend this approach more highly for the following reasons: + +- Existing webservers are generally more reliable and performant +- It allows configuration of an SSL certificate, which is necessary for protecting your users' data + +Upon configuring the webserver, you'll need to instruct it to forward traffic to the running Prose server. + +Your setup might look something like this: + +- Nginx is configured to listen on port 80 and port 443 on your domain, `purplemonkeydishwasher.tech` +- Nginx has located and loaded your SSL certificate files for `purplemonkeydishwasher.tech` +- Nginx is configured to upgrade all requests on port 80 to port 443 +- Your Prose server is running inside of Docker on a container port of 80, and exposed to the host on port 8080. +- Your Nginx configuration specifies that requests to `purplemonkeydishwasher.tech` should be forwarded to port 8080. +- Requests come in for `purplemonkeydishwasher.tech`, Nginx routes it to the container running Prose, which handles the requests, and responds. + +#### Configure your Cloud Provider's Firewall, if one exists + +Ideally, you've configured Prose to be exposed on the open internet with the traffic encrypted over port 443. + +Depending on your cloud provider, you may need to go into its settings and expose that port on the firewall. + +For example, in DigitalOcean, this involves going to the Networking section, and creating a new firewall rule. + +From there, it is fairly simple to add common ports, like 80 and 443, to the firewall. + +After that, you simply apply the firewall to your particular instance, and traffic should be allowed through. + +#### Configure DNS Settings for your Domain + +Provided that you've already registered a domain name, you'll need to configure it so that the domain name points to your host which is running Prose. + +Depending on your setup, this will either be done in your domain provider's settings panel, or perhaps within your cloud provider. + +Continuing with the DigitalOcean example from above, you can configure your domain provider to point at DigitalOcean's name servers. + +This effectively tells your domain provider that DigitalOcean will handle everything for you, and allows you to make adjustments to your domain from within DigitalOcean. + +In that case, DigitalOcean makes it seamless to map the domain name to your instance's IP address, and it should then be accessible from the domain name. + +Otherwise, you'll want to get the IP address of your host, go into your domain provider, and instruct it that requests to your domain should be direct to your host's IP address. + +#### Ready to Go + +At this point, your deployed host should be running Prose correctly. When you navigate to the domain name that you configured it with, you should see [GraphiQL](https://www.graphql-yoga.com/docs/features/graphiql), which will allow you to make GraphQL queries against your Discourse instance. + +We understand that the details of your deployment can vary quite a bit depending on how you chose to do it. + +If you run into any issues with this step—as always—don't hesitate to reach out to us for support. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/deployment.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/deployment.md new file mode 100644 index 00000000..b46ab73b --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/deployment.md @@ -0,0 +1,86 @@ +--- +title: Overview +--- + +As covered in [Concepts and Architecture](concepts#prose-discourse-through-graphql), Prose is Lexicon's GraphQL API layer on top of the traditional RESTful API provided by Discourse. + +## Getting Started with Deployment + +At this point, you're likely to be digging into this section of the documentation for two reasons: + +- You've been developing against a local instance (or container) running Prose, and you're ready to actually deploy your entire Lexicon project to production. + +- You want to simplify your development process by pointing the Lexicon Mobile App at a deployed instance of Prose. + +In either scenario, the end goal of this section is to have a working Prose server accessible on the open internet. + +### 🔐 Note about Access Control + +As a brief aside, please note that Prose cannot expose any information from Discourse that Discourse is not already exposing on its own. + +If your Discourse instance requires authentication, then Prose will be unable to retrieve most queries unless the required authentication information is provided by the user accessing Prose. + +### 🧱 Alternative Deployment Strategies + +Initially, we wanted to provide instructions for an integrated deployment strategy. This would have involved deploying Prose on the same host as your Discourse instance, and ideally finding a way to deploy and expose it within the running Docker host that Discourse uses itself. + +This is still achieveable. But for now, we have opted to focus solely on deploying Prose as a dedicated instance. + +However, should you find yourself preferring a custom deployment of Prose, we would encourage you to do so. + +If you do, and you have some questions or challenges you're encountering, please reach out to us. + +Ideally we can help you sort things out and work your approach into our documentation so that everyone will benefit going forward. + +## Deploying as Dedicated Instance + +As mentioned above, the official deployment strategy for Prose is to host it as a dedicated instance. + +Like anything, this comes with both benefits and trade-offs, which we have outlined for you below. + +### 🚀 Benefits + +A dedicated host for Prose will have better performance and reliability because its only resource usage comes from running Prose. i.e., it has exclusive usage of CPU, RAM, disk space, etc. + +If, on the other hand, you had managed to deploy Prose on the same host as your Discourse instance, this would mean that both Prose and Discourse need to share the host's allocated resources. If your Discourse instance is already running on a fairly light host, running Prose on it might mean that you would need to upgrade to a host with more resources. + +### ⚠️ Possible Trade-offs + +#### Increased Cost + +Naturally, if you're setting up a dedicated host to run Prose, then that involves additional costs on top of what you're already paying to host Discourse. + +Having said that, for most deployments, it is unlikely that you will need to allocate an expensive amount of resources to Prose. + +For example, on Digital Ocean, the $5 Shared CPU node is often sufficient. + +#### Potential for Increased Latency + +By nature, when deploying Prose on a different host from your running Discourse instance, the latency between the mobile app and Discourse increases. + +This is because each request has to make two hops: + +- The first request is from the client (your Lexicon-powered mobile app) to the Prose GraphQL API +- The second request is from Prose to Discourse + +However, the only important questions regarding this point are: + +- How much measurable latency is there? +- Is it noticeably slow to myself or my users? + +This, of course, can depend on several factors: + +- Where your Discourse server is deployed +- Where your Prose server is deployed +- Where your users tend to be +- If the amount of traffic (load) is too much for the system to optimally run both Prose and Discourse. + +If you are observing noticeable latency, we would recommend looking into these factors. + +Ideally, you'll want to deploy Prose in the same region as your Discourse instance; and it is even better if you can deploy Prose in the same datacenter as your Discourse instance. + +## Up Next + +With this overview out of the way, we'll start by introducing you to the list of all possible [environment variables](env-prose) that may be necessary or useful when deploying Prose. + +Lastly, we'll get into the heart of it, by [preparing your host and deploying Prose](dedicated). diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/discourse-features.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/discourse-features.md new file mode 100644 index 00000000..3183014a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/discourse-features.md @@ -0,0 +1,52 @@ +--- +title: Discourse Features Support +--- + +Below is a table of Discourse features which provides the details and current status about the support for a given feature in the **Lexicon Mobile App**. + +If we missed one, or anything looks out of date here, don't hesitate to submit a Pull Request which updates the table. + +Is the feature you love not supported? [Reach out to us](mailto:support@kodefox.com) to discuss how we can bring it to life for you. + +#### Our General Approach to Feature Support + +Much of our initial focus was on using-facing features, rather than administrative features. + +This is why, for example, users can select categories for their topics, but administrators are unable to create new categories from within the mobile app. + +For this reason, most admin tasks are still best accomplished using the Discourse web app on a larger device. + +### Lexicon Mobile App Features + +| Feature | Description | Supported | Notes | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- | +| 2FA Login | Allow users with 2FA enabled to be prompted for their 2FA code when logging in | ✅ | Managing 2FA, such as enabling it or disabling it from within the app, is not currently supported | +| Ability to Tag Topics | Create and tag topics to provide relevant metadata for your users | ✅ 🔧 | Configuration required: see [Optimal Experience](optimal#enable-topic-tagging) | +| Topic Previews (Excerpts) | Show an excerpt of the first post in a topic from the Home screen | ✅ 🔧 | Configuration required: see [Optimal Experience](optimal#enable-topic-excerpts) | +| View User Activity | View a user's recent activity—such as topics, posts, and likes—in a single feed from their profile | ✅ | The ability to filter by activity is not currently supported | +| Topic Metrics | Likes, Views, Replies, and Frequent Posters | ✅ | | +| Topic & Post Actions | Ability to like and edit topics and posts | ✅ | | +| View Top & Latest Topics | A Tab View at the top of the main feed provides the ability to switch between Latest and Top activity | ✅ | | +| Search | Search the current Discourse instance for topics and posts based on keywords, categories, and tags | ✅ | | +| Categories | View the category of a topic and filter topics by a given category | ✅ | Categories cannot be created, updated, or deleted | +| Attaching Media to Posts | Users can attach media to a post from the app | ✅ 🔧 | Configuration recommended for supported file extensions-see [Optimal Experience](optimal#configure-upload-extensions) | +| Standard Markdown | Standard Markdown is supported in the editor and rendered correctly in the mobile app | ✅ | Light, incomplete support exists for some of Discourse's custom markup, such as dates | +| Sign Up | Allow users to sign up for an account directly through the mobile app, depending on whether your Discourse instance allows new user registration or not | ✅ | | +| Browsing Public Instances | Allow users to immediately access and browse your Discourse instance from the mobile app if it is not private | ✅ | Users will be prompted to login upon attempting an authenticated action | +| User Profiles | Ability to view users' profiles and edit your own | ✅ | Partial support: displays the user's photo, username, Markdown bio on a single line, and recent activity | +| Post Flagging | Allow users to flag posts for admins to review | ✅ | Admins are not able to review posts in the app, though they will see in-app notifications for flags | +| In-App Notifications | Allow users to see new notifications from the profile screen of the mobile app and mark all notifications as read | ✅ | Some notifications from Discourse are not tappable in the mobile app, such as badge notifications | +| Private messaging | Allow users to start private or group messages with one another | ✅ | | +| Mentions | Allow users to mention a user when creating or editing posts and messages | ✅ | +| Color Scheme | Provides light and dark mode support for users | ✅ | Specify color scheme (light mode, dark mode, or system) from within the app (only local to the user's mobile device) | +| Badges | The ability to see and interact with badges that have been awarded to users on the Discourse instance | ❌ | | +| Post Drafts | Enable users to start composing a draft of a post and return to it later | ❌ | | +| Groups | Enable users to create and participate in private groups of which only group members can view certain topics | ❌ | | +| Admin Features | Discourse admin features generally not available in Lexicon—better suited to a desktop environment | ❌ | Editing posts is supported | +| Post Quotes, Polls, Toggles, and Task Lists | Custom text formatting that enables Discourse-specific features | ❌ | | +| Discourse Emojis | Utilize emojis when creating a topic, making a post, or sending a reply | ❌ | Unicode-based emojis are of course supported | +| Post Bookmarks | Allow users to bookmark certain posts or topics | ❌ | | +| DiscourseConnect (SSO) | Replace Discourse authentication with a Custom Provider | ❌ | | +| Custom Authentication Plugins | Login via OAuth2 or other protocols using custom Discourse Plugins | ❌ | | +| Real-time Chat | Enable users to initiate conversations using the chat feature, either in a channel or through private messaging | ❌ | | +| User Status | Allow other user in community to see user message status | ❌ | | diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/env-mobile.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/env-mobile.md new file mode 100644 index 00000000..79af9933 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/env-mobile.md @@ -0,0 +1,119 @@ +--- +title: Configuration Values +--- + +You can check and set the configuration values in `frontend/Config.ts`. + +The table below describes the configuration values for the Lexicon Mobile App. + +If there is a default value indicated, you do not need to set it. + +| Variable | Required | Notes | Default Value | Example Value(s) | +| -------------------- | -------- | -------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| proseUrl | Yes | The url of the Prose Server (must start with http or https) | - | https://prose.myserver.com https://prose.myserver.com:8080 https://prose.myserver.com/subpath https://prose.myserver.com:8080/subpath | +| inferDevelopmentHost | No | The flag (true / false) to override localhost with the host of the development machine | (empty) | true | + +## The `config` object + +In the `Config.ts` file, you'll find a `config` object that allows you to specify configuration values by scenario. + +The two primary scenarios are: + +- `localDevelopment`: when developing against the app locally. This configuration is also used as a fallback for an unknown build channel. +- `buildChannels`: used to define configuration by build channel when building the app with the EAS CLI. + +Primarily, you'll only be concerned with configuring `proseUrl` for each of these sections. + +## `proseUrl` + +:::caution +`proseUrl` must always be specified, with or without a port number, and must always start with either `http://` or `https://`. +::: + +`proseUrl` is used to specify the URL of the Prose GraphQL API. + +The Prose GraphQL API acts a middleman between the Lexicon Mobile App and your Discourse instance. Without it, the mobile app cannot interact with your Discourse instance. + +### Example + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com', + }, + production: { + proseUrl: 'https://prose.myserver.com', + }, + }, +}; +``` + +With this configuration above, the app will: + +- point at `http://localhost:8929` when you run the app using `npm run start` +- point at `https://preview.myserver.com` when you build the app using `eas build --profile preview` +- point at `https://prose.myserver.com` when you build the app using `eas build` + +`proseUrl` also can include a subpath if desired: + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com:8080/subpath', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +**Different Behavior in Development** + +When running the app locally, if `proseUrl` is set to `http://localhost` or `http://127.0.0.1`, it will replace `proseUrl` with the IP address of your development machine. It does this by using Expo's `debuggerHost` constant. + +_Note: this does not apply when building the app._ + +This addresses multiple issues: + +- Accessing `localhost` from within the Android simulator does not map to your development machine +- Accessing `localhost` from a device running Expo Go does not map to your development machine + +Both of these scenarios would otherwise require you to manually identify and specify your development machine's IP address with `proseUrl`. This is bothersome since your machine's IP address can change over time. + +If you are interested in more details about this, the implementation of this behavior is available in `frontend/constants/app.ts`. + +This behavior of automatically overriding those values can be disabled, with `inferDevelopmentHost`, which is covered below. + +## `inferDevelopmentHost` + +:::info +This flag is only valid under `localDevelopment`. It has no effect when used as part of `buildChannels`. +::: + +When in development, by default, the Lexicon Mobile App will check to see if `proseUrl` is set to either `http://localhost` or `http://127.0.0.1`. + +When detected, either of those values will be overwritten with the IP address of your development machine. + +This is a very useful feature that makes on-device testing simply work out of the box without needing to manually specify your IP address (or update it when it changes). + +For scenarios where this behavior is not desirable, `inferDevelopmentHost` can be used as a flag to disable this behavior. It can be disabled by specifying the value as `false`. + +When set to `false`, this behavior of overriding `proseUrl` with the development machine's IP address will no longer occur, and the original value will be passed through as-is. + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + inferDevelopmentHost: false, + }, +}; +``` diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/env-prose.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/env-prose.md new file mode 100644 index 00000000..59901fd5 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/env-prose.md @@ -0,0 +1,15 @@ +--- +title: Prose Environment Variables +--- + +The table below lays out environment variables for the Prose GraphQL API. + +If there is a default value indicated, you do not need to set it. + +| Environment Variable | Required | Notes | Default Value | Example Value | +| --------------------------- | -------- | ----------------------------------------------------------------------------------- | ---------------------- | ------------------------------------ | +| PROSE_DISCOURSE_HOST | Yes | The specific location of your Discourse instance. | - | https://discourse.example.com | +| PROSE_DISCOURSE_UPLOAD_HOST | No | Instruct Prose to use a different host for file uploads to Discourse. | | https://upload.discourse.example.com | +| PROSE_APP_HOSTNAME | No | The **application-level** hostname that Prose will listen on. | localhost | 0.0.0.0 | +| PROSE_APP_PORT | No | The **application-level** port that Prose will listen on. | 80 | 8080 | +| SKIP_CHECK_DISCOURSE | No | Bypass the startup process of checking the provided Discourse host for reachability | false | true | diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/intro.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/intro.md new file mode 100644 index 00000000..4684df41 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/intro.md @@ -0,0 +1,148 @@ +--- +id: intro +title: Introduction +slug: / +--- + + + --- iOS Auth + + + + --- iOS Dark Mode + + + + --- iOS Comment + + + + --- iOS Message + + --- Android Auth + + + + --- Android Dark Mode + + + + --- Android Comment + + + + --- Android Message + + + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Carousel from 'react-bootstrap/Carousel'; + +--- + +:::info +Coming Soon! + +Lexicon v2.0.0 is currently in beta, and includes support for push notifications along with other features. + +See the [v2 documentation](../version-2.0.0/intro.md) for more details. +::: + +Lexicon is a customizable, pre-built mobile app that provides an elegant mobile discussions experience. Built on top of [Discourse](#what-is-discourse). + +## Features + +- Topics, Private Messaging, User Signups, Profile Management, and more. +- Straightforward process to [**customize**](white-labeling) the app for your brand +- Rapidly build Android and iPhone apps for your existing Discourse site +- Backed by a [GraphQL](https://graphql.org/) API +- Free and open source! +- [Commercial support](commercial-support) available + +## Benefits + +- Launch a custom mobile discussions app +- Increase engagement with your users by adding a mobile-first Discourse experience—no more [WebViews](https://www.kirupa.com/apps/webview.htm). +- Built with [React Native](https://reactnative.dev/) and [Expo](https://expo.io), delivering a native look-and-feel on both iOS and Android. +- Includes an auto-documented [GraphQL](https://graphql.org/) [interface](concepts#prose-discourse-through-graphql) over the Discourse API, which you can build on top of. + +## Screenshots + +### iOS + + + + IOS Lexicon Login Page + IOS Lexicon Signup Page + IOS Lexicon Home Page + + + IOS Lexicon Dark Mode in Home Page + IOS Lexicon New Post Page + IOS Lexicon Post Detail Page + + + IOS Lexicon Comment Section + IOS Lexicon Profile Page + IOS Lexicon Notification Page + + + IOS Lexicon Message Page + + + +### Android + + + + Android Lexicon Login Page + Android Lexicon Signup Page + Android Lexicon Home Page + + + Android Lexicon Dark Mode in Home Page + Android Lexicon New Post Page + Android Lexicon Post Detail Page + + + Android Lexicon Comment Section + Android Lexicon Profile Page + Android Lexicon Notification Page + + + Android Lexicon Message Page + + + +## How does Lexicon work? + +Lexicon delivers a native mobile Discourse experience with **two key components**: + +- The [**Lexicon Mobile App**](#the-lexicon-mobile-app) - a modern mobile app built with [Expo](https://expo.io) & [React Native](https://reactnative.dev/) +- [**Prose**](#prose-discourse-through-graphql), our GraphQL API on top of the Discourse API + +### The Lexicon Mobile App + +The Lexicon Mobile App is built with [Expo](https://expo.io), which allows us to maintain both the iOS and Android apps with a single codebase. + +For those unfamiliar, Expo provides a superior development and deployment experience on top of [React Native](https://reactnative.dev/). + +### Prose: Discourse through GraphQL + +Prose is Lexicon's [GraphQL](https://graphql.org/) layer built on top of Discourse's API. + +This enables developers to quickly build apps on top of a live Discourse instance while leveraging the [benefits of GraphQL](https://www.apollographql.com/docs/intro/benefits/). + +### What is Discourse? + +Discourse is open-source **discussion software** that is thoughtfully designed, simple to setup, and well-maintained. + +You can learn more about it on the [Discourse website](https://www.discourse.org/). + +### Further Details + +You can learn about the technical details of our approach in [Concepts & Architecture](concepts). + +## License + +MIT. Copyright (c) [Lexicon](https://github.com/lexiconhq) diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/lexicon-updates.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/lexicon-updates.md new file mode 100644 index 00000000..43d95945 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/lexicon-updates.md @@ -0,0 +1,17 @@ +--- +title: Receiving Updates from Lexicon +--- + +Due to the nature of this project, the best way to synchronize bugfixes, updates, and other changes to the Lexicon Mobile App is to treat your app like a fork of our repository. + +In the process of customizing the Lexicon Mobile App for your needs, you might make any number of changes to the theme or assets. + +However, the underlying codebase should be—for the most part—untouched. + +When we release a bugfix or new feature on the `master` branch, you'll be able to pull down our changes, resolve any conflicts with your changes, and have an updated version of your app ready to republish. + +It is worth acknowledging that this approach, which effectively uses Git to solve this problem in a fairly simple way, could be improved. + +Provided that there's enough interest, we might later decide to shape Lexicon into more of a standalone SDK package that you can import and receive updates to via npm. + +If you're interested in making that a reality, please reach out to us! diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/optimal.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/optimal.md new file mode 100644 index 00000000..a06199e7 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/optimal.md @@ -0,0 +1,89 @@ +--- +title: 'Optimal Experience' +--- + +If you're planning to make use of the Lexicon Mobile App, there are a few settings you should tweak on your Discourse instance to provide the best in-app experience to your users. + +## Enable Topic Excerpts + +We have designed the Mobile App so that users can easily see the first few sentences of a topic as they scroll through the topics list. + +However, by default, Discourse does not return excerpts when listing topics. + +Fortunately, there is a secret setting that enables this. + +It just takes a bit of additional configuration to enable. + +While Discourse does enable opting into this behavior as part of a [Theme Component](https://meta.discourse.org/t/topic-list-excerpts-theme-component/151520), we wanted to guide you through the option of toggling the setting itself. + +Should you prefer to enable it using the above theme component, you're free to do so. + +Enabling this setting involves gaining access to the server and changing a setting. + +### Instructions + +The original instructions can be found [here](https://meta.discourse.org/t/discourse-as-a-simple-personal-blog-engine/138244/4). + +Once you've gained access to your server, enter into the running Discourse app. + +```sh +$ /var/discourse/launcher enter app +``` + +Next, enter the Rails CLI: + +```sh +$ rails c +``` + +Finally, set the setting to true: + +```sh +$ SiteSetting.always_include_topic_excerpts = true +``` + +After that, you can exit, and excerpts should now be displaying in the app. + +## Enable Topic Tagging + +The Lexicon Mobile App was designed with the ability to tag topics in mind. + +This allows users to view and manage tags on topics, which is a popular feature on many Discourse servers. + +Unfortunately, this is not enabled by default. + +### Instructions + +In order to enable it, you can take the following steps: + +- Navigate to the Admin Site Settings page at `/admin/site_settings` +- Use the search bar to search for the setting `tagging enabled` +- Ensure that it is checked +- If you made a change, click the green checkbox button to apply it + +Topics should now be taggable, and viewable in the app. + +## Configure Upload Extensions + +Discourse provides a security feature that allows Discourse admins to specify a whitelist of file extensions that their users can upload. +For example, most admins would choose to restrict uploading of `.exe` files. +In order to be compatible with the settings of your Discourse instance, the Lexicon Mobile App simply requests the list of allowed extensions and uses it to enforce allowed extensions in the app. +Out of the box, most Discourse instances support this default list of extensions: + +- `.jpg` +- `.jpeg` +- `.png` +- `.gif` +- `.heic` +- `.heif` + +If you'd like to adjust the list of extensions in your Discourse instance, you can do so by following the instructions below. + +### Adjusting Allowed Extensions in Discourse + +- Navigate to the Admin Site Settings page at `/admin/site_settings` +- Use the search bar to search for the setting `extensions` +- Find the setting labeled `authorized extensions`. +- Adjust the list as you see fit to include the file extensions you'd like your users to be able to upload. +- When you are done making changes, click the green checkbox to apply them. +- The Lexicon Mobile App will receive the updated list of extensions from your site settings and begin enforcing it for your users. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/play-store.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/play-store.md new file mode 100644 index 00000000..dacdfa8c --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/play-store.md @@ -0,0 +1,162 @@ +--- +title: Publishing to the Play Store +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Prerequisites + +:::note +If you don't already have a Google Developer account, note that there is a fee to create one. +::: + +- A [Google Developer Account](https://play.google.com/console/signup) to access the [Google Play Console](https://play.google.com/console) +- An Expo account +- EAS CLI 2.6.0 or newer + +## Google Play Console + +The [Google Play Console](https://play.google.com/console) enables you to setup your app, invite beta testers, and publish your app to the [Google Play Store](https://play.google.com/store). + +Because you're publishing an app that was built using Expo, it is **very important** that you follow [Expo's instructions](https://github.com/expo/fyi/blob/master/first-android-submission.md) for submitting an app to the Google Play store correctly. + +## App Configuration + +After setting up your app in the Google Play Console, there are some other adjustments you'll need to make. + +### Build Config + +Similar to the approach for [Publishing to the App Store](app-store), if you haven’t already, you'll need to set your app name and slug in `frontend/app.json`. The [slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) is used as part of the URL for your app on Expo's web services, so it is recommended to use kebab-case (e.g., `my-lexicon-app`). + +Replace these placeholders with your desired values: + +```json + "name": "", + "slug": "", +``` + +Then, you need to configure EAS Build by running the following command, or skip to the next [step](play-store#setup-config-values): + +```bash +eas build:configure +``` + +The EAS CLI will prompt you to specify `android.package` and `ios.bundleIdentifier` if those values are not already provided in `app.json`. + +Next, verify that the `package` name and other details specific to your app are included in the `android` section of `app.json`. Note that the `versionCode` will be automatically updated when you build the app with the `production` profile, so you don't need to increment the version manually. + +Also, there's one further detail that you might want to add, depending on your app's permissions. + +In the example below, we're providing our app with the ability to read and write to external storage. + +```json + "android": { + "package": "", + "permissions": [ "READ_EXTERNAL_STORAGE" , "WRITE_EXTERNAL_STORAGE" ] + "versionCode": 1, + }, +``` + +If your app requires further permissions, be sure to specify them as needed in this part of the configuration. + +If you don't quite understand how permissions work yet, it's best to check out the [Expo documentation](https://docs.expo.io/versions/latest/sdk/permissions) on this topic in order to get a full understanding. + +### Setup Config Values + +:::info +When publishing your app, it is necessary to deploy Prose somewhere publicly accessible, perhaps on a cloud hosting provider like AWS or DigitalOcean. If Prose is only running on your local machine, users that download your app won't be able to use it. +Check [the documentation](deployment) to deploy Prose if you haven't already. +::: + +Next, set the **Prose URL** for your builds in `Config.ts`. You can set a different URL for each build channel. + +:::note +In the original release of Lexicon, the **Prose URL** was specified in `frontend/.env`. However, as part of migrating to Expo's EAS feature, we centralized the configuration into `frontend/Config.ts` to save you the trouble of needing to maintain it in more than one place, as suggested in the [Expo documentation](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update) +::: + +```ts +const config = { + // ... + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, +}; +``` + +### Add the Play Store Secret File + +For the last step, you'll need to provide a `.json` file containing a private key in order to interact with the Play Store. Follow [this guide](https://github.com/expo/fyi/blob/main/creating-google-service-account.md) to generate one. Then, copy the JSON file to your `lexicon/frontend` directory, and rename the file as `playstore_secret.json`. + +The JSON file looks like this: + +```json +{ + "type": "service_account", + "project_id": "", + "private_key_id": "", + "private_key": "-----BEGIN PRIVATE KEY----------END PRIVATE KEY-----\n", + "client_email": "", + "client_id": "", + "auth_uri": "", + "token_uri": "", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/lexicon%40api.iam.gserviceaccount.com" +} +``` + +## Build your App for Android + +Because we're working with Expo and React Native, this step isn't too different from building your app for iOS. + +From the `frontend/` directory, you can run this command to check the app before publishing: + +```bash +eas build --platform android --profile preview +``` + +Running `eas build` with the `preview` profile will build the app as an APK. This allows you to quickly load it onto your Android device or emulator. After the build is done, navigate to your project in the [Expo web console](https://expo.dev), then click on the **Builds** menu located on the left-hand side of the screen. + +- Click on the project you want to install. + + Builds + +- Download the app by pressing the `Install` button in the `Build Artifact` section. + + Build Artifact + +You can download and launch the app on your real device, or drag the downloaded APK file to your emulator. + +Once you have verified that the app runs as expected, you can proceed to build it for release: + +```bash +eas build --platform android --profile production +``` + +The approach for a production build is similar to the one used for generating a preview build. However, unlike a preview build, you won't be able to launch the production build in Android emulator—it is intended solely for publishing to the Play Store. + +Once this process is completed, you can proceed with submitting it to the Play Store. + +## Publish to the Play Store + +At this point, you can take your app live on the Google Play Store, or you can proceed with internal testing on the Google Play Console. + +To proceed with internal testing, run this command: + +```bash +eas submit --platform android --profile staging +``` + +To release your app publicly, run this command: + +```bash +eas submit --platform android --profile production +``` + +You can read more about build profiles [here](tutorial/publishing). + +At this point, provided that you've completed all the steps, congratulations! Your Lexicon-powered mobile app is now live and ready to be downloaded by your users. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/publish-app.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/publish-app.md new file mode 100644 index 00000000..267f3e1a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/publish-app.md @@ -0,0 +1,11 @@ +--- +title: Publishing your App +--- + +:::danger Progress +This page has not been started yet or needs a lot more work. +::: + +Expo workflow, benefits of, etc. + +Over the air updates? diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/quick-start.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/quick-start.md new file mode 100644 index 00000000..c72f310c --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/quick-start.md @@ -0,0 +1,66 @@ +--- +title: Quick Start +--- + +## Prerequisites + +- Node.js 16.14 or newer +- The latest version of NPM or Yarn, compatible with Node 16.14 or newer +- Expo CLI 6.0.6 or newer +- EAS CLI 2.6.0 or newer to build and publish the App +- An active Discourse site + - If you don’t have one, please follow the instructions in [Development Setup](setup#discourse-host) + +:::note +Follow the instructions in [Setup Guidance](tutorial/setup) to install the prerequisite depedencies, such as NPM, the Expo CLI, and the EAS CLI. +::: + +## Installation + +Clone the repository and navigate into it: + +``` +git clone git@github.com:lexiconhq/lexicon.git +cd lexicon +``` + +Next, install the project's dependencies and generate its GraphQL schema: + +``` +$ npm install && npm run generate +``` + +Note that `npm run generate` involves two steps. + +- First, it will generate a [GraphQL schema](https://nexusjs.org/docs/guides/schema) in the `api` directory. + +- Then, using the generated schema, it will create a new folder called `generated` in the `frontend` directory, containing the resulting query and mutation types. + +- This allows the frontend codebase to stay in sync with, and not duplicate the code for, the types from the `api` directory. + +The code shared from the API is then used by [Apollo](https://github.com/apollographql/apollo-tooling), the GraphQL library we use on the frontend, which enables the Mobile App to query the API correctly. + +## Launch the Mobile App + +You can run the app and test it out by running this command from the project root: + +``` +$ npm run quickstart +``` + +This will simultaneously launch two processes: + +- The Prose GraphQL API Server +- The local Expo dev server, which will enable you to launch the React Native app from your device + +**Please note that this takes some configuration to setup properly**. + +- The `quickstart` command configures the Mobile App and the Prose GraphQL API to point at https://meta.discourse.org, as an example. + +- You'll need to make adjustments to point at a site of your choice. + +- The Lexicon Mobile App (via Expo) must be configured to point at the Prose GraphQL Server + +- The Prose GraphQL Server must be configured to point at an active Discourse instance + +More details are available in the [Development Setup](setup) section diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/rationale.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/rationale.md new file mode 100644 index 00000000..bfb62fa4 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/rationale.md @@ -0,0 +1,73 @@ +--- +title: Background & Motivation +--- + +### Discourse's Approach to a Mobile Experience + +Discourse is a phenomenal, battle-tested piece of software that facilitates thoughtful discussions in countless communities around the globe. It's no secret that we are big fans of it. + +The Discourse core team's strategy for mobile devices was to implement their product as a responsive website, and optimize for mobile use cases. This allowed mobile users to simply go to the same Discourse site as they would have on devices with larger screens— enabling them to view and write posts from their mobile devices. + +However, over time, interest in a dedicated Discourse mobile app grew. The core team addressed this need by building a native mobile app. They chose to reuse their existing work by having the app simply wrap a webview containing the mobile site. + +This was a nice improvement, as it allowed the mobile app to integrate with native SDKs and provide some additional features to Discourse mobile users. + +Overall, their approach to solving this problem was both efficient and well-done. + +However, it is still evident to many users that they're interacting with an embedded web browser, and it's clear that it's not a mobile-_first_ experience. + +For many users and site-owners, what the Discourse team has provided is more than enough, and it solves all of their problems. + +In our case, we were looking for a very specific type of experience. + +### Who We Are + +The Lexicon Team is part of [KodeFox](https://www.kodefox.com/), a software studio comprised of passionate software engineers, designers, and product managers who regularly build world-class software for our customers. + +Interested in custom software development with a personal touch? Drop us a line at [hello@kodefox.com](mailto:hello@kodefox.com). + +### Enter Lexicon + +Lexicon was formed out of the desire to further leverage many of the great features that the Discourse team had worked hard to build. + +In our consulting projects, we found that many of our clients were regularly asking for solutions that Discourse already provides out of the box. + +However, our clients wanted a seamless, native mobile experience, tailored to the brand that their users were already familiar with. + +After digging into the Discourse API documentation, we felt that it was worthy investment to build a mobile-first Discourse experience which also faciliated customizability. + +We were already fluent with the elegant development process provided by React Native and Expo, so it was a natural fit for us to build the mobile app with these technologies. + +This allowed us to achieve a high ratio of code reuse across iOS and Android, making feature implementations and bug fixes a much simpler process in most cases. + +In integrating with Discourse's API, we also noticed that the API documentation contains a disclaimer which encourages reverse-engineering to understand it. + +While we can appreciate the sentiment of figuring things out yourself, we wanted to provide an API experience that makes it easy for developers to dig into interactive documentation and quickly grasp the concepts. + +For this reason, we also chose to build Prose, our GraphQL API layer on top of the Discourse RESTful API. Another motivating factor was our existing fluency with GraphQL. + +This allowed us to quickly implement the mobile app with an intuitive API paradigm that we were already very familiar with. + +#### How Lexicon can help you + +If you already run an existing Discourse site and want a native mobile experience for your users, you can very quickly point Lexicon at your site and browse it in real-time from your device. + +Check out the [Quick Start](quick-start) page to see a rapid example of spinning up a mobile app for Discourse's own [Meta site](https://meta.discourse.org). + +But beyond that, Lexicon is an open source pre-built mobile app. This means that you can customize it to fit your brand. + +You can think of it like a template that you can use to build your own mobile app for your community. + +If you're interested in customizing the Lexicon Mobile app, you can learn more about that in the [White Labeling](white-labeling) section. + +And when you're finished, you can publish it to the Apple App Store or Google Play Store, which we cover in [Publishing your App](app-store). + +### FOSS Mindset + +Finally, while this project will benefit us and our clients in the future, we also wanted it to be a gift to the community. + +We recognize and support the culture of free and open-source software. That's why we're delighted to give back to the community in this way, just as the Discourse team originally did when they chose to open-source their hard work. + +So please engage with us on Github, and don't be shy about opening a new issue or even a PR. + +We look forward to working with you! diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/setup.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/setup.md new file mode 100644 index 00000000..7ef46648 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/setup.md @@ -0,0 +1,362 @@ +--- +title: Development Setup +--- + +### Clone the Lexicon Repository + +If you haven't already, make sure you [clone the Lexicon repository](quick-start#installation) from Github. + +### Setup a Discourse Instance, if necessary + +In order to get started developing against the Lexicon Stack, you'll need a running Discourse instance. + +To recap, the Lexicon Stack consists of: + +- The Lexicon Mobile App +- The Lexicon Prose GraphQL API +- A running Discourse instance + +Without a Discourse instance, the Prose GraphQL API has nowhere to retrieve data from. And when the Prose GraphQL API can't retrieve any data, the Lexicon Mobile App won't be able to receive anything either. + +For detailed instructions on setting up a local development instance of Discourse, head over to the [tutorial](./tutorial/setup-discourse), which will walk you through the process. + +However, if you already have a deployed instance of Discourse, we'd recommend using that instead. + +### Configuration + +The [Lexicon Stack](concepts#architecture-of-the-lexicon-stack) requires some configuration in order to properly interact with your Discourse server. + +This involves configuring both the backend GraphQL API, which interacts with your Discourse instance; as well as the frontend Mobile App, which interacts with the GraphQL API. + +The architecture of this setup is depicted in [Architecture of the Lexicon Stack](concepts#architecture-of-the-lexicon-stack). + +#### Backend GraphQL API Configuration + +The [Prose GraphQL API](concepts#prose-discourse-through-graphql) is fairly simple in terms of configuration. In the simplest case, it only needs to know where your Discourse instance is accessible at. + +It receives its configuration via a [`.env` file](https://www.codementor.io/@parthibakumarmurugesan/what-is-env-how-to-set-up-and-run-a-env-file-in-node-1pnyxw9yxj) in the root of the `api/` directory. + +Here is the simplest configuration of the `api/.env` file: + +``` +PROSE_DISCOURSE_HOST=https://meta.discourse.org +``` + +It is also worth noting that you can optionally configure the **Hostname** and **Port Number** that the Prose API server listens on, both of which default to **localhost** and **port 80**, respectively. + +``` +PROSE_DISCOURSE_HOST=https://meta.discourse.org + +# Instruct Prose to broadcast publicly instead of on localhost +PROSE_APP_HOSTNAME=0.0.0.0 + +# Instruct Prose to listen on port 8929 instead of the default port 80 +PROSE_APP_PORT=8929 +``` + +For a comprehensive list of all environment variables that can be used to configure Prose, check out [Prose Environment Variables](env-prose). + +#### Frontend Mobile App Configuration + +:::note +In the original release of Lexicon, the **Prose URL** was specified in `frontend/.env`. However, as part of migrating to Expo's EAS feature, we centralized the configuration into `frontend/Config.ts` to save you the trouble of needing to maintain it in more than one place, as suggested in the [Expo documentation](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update) +::: + +To configure the frontend mobile app, you'll first need to set your app name and slug in `frontend/app.json`. The [slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) is used as part of the URL for your app on Expo's web services, so it is recommended to use kebab-case (e.g., `my-lexicon-app`). + +Replace these placeholders with your desired values: + +```json + "name": "", + "slug": "", +``` + +Next, change the value of `proseUrl` in `frontend/Config.ts` to the URL of your Prose GraphQL API—whether local or already deployed somewhere. + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com:8080/subpath', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +`localDevelopment.proseUrl` will be used during development when you run the app using `npm run start` or `expo start`, whereas the specific value within `buildChannels` (e.g., `production.proseUrl`) will be used when actually building the app. + +#### Development Scenarios + +When developing locally, there are at least three scenarios that you may find yourself in. + +Depending on which one applies to you, the config values across `frontend/Config.ts` and `api/.env` may need to be set differently. + +##### Scenario 1: Existing Prose Deployment + +If you've already deployed the Prose GraphQL API to a host that is publicly reachable, you will have already setup `api/.env` with the proper values. + +In that case, `frontend/Config.ts` only needs updated to point at the deployed GraphQL API. + +For example: + +```ts +const config = { + localDevelopment: { + proseUrl: 'https://my-deployed-graphql.api', + }, + buildChannels: { + preview: { + proseUrl: 'https://my-deployed-graphql.api', + }, + production: { + proseUrl: 'https://my-deployed-graphql.api', + }, + }, +}; +``` + +In the example above, we have configured the app to point at `https://my-deployed-graphql.api` in all scenarios, including during development when running with `npm run start`. + +##### Scenario 2: Run Prose Locally & Access from a Simulator + +This approach involves running both the Lexicon Mobile App and the Prose GraphQL API on your development machine. It is accomplished by instructing Expo to launch the Mobile App in the Android or iOS simulator. + +When developing this way, you can simply set `localDevelopment.proseUrl` to `http://localhost` in `frontend/Config.ts`. And then in `api/.env`, you can set `PROSE_APP_HOSTNAME` to `0.0.0.0`. + +Note that if you want to run Prose locally on a specific port, you would need to make sure that the configuration in both `api/.env` and `frontend/Config.ts` reflect that correctly. + +:::caution +If you configure `PROSE_APP_HOSTNAME` in `api/.env` to only listen on `localhost` or `127.0.0.1` (rather than `0.0.0.0`), it prevents others on the same network as your development machine from accessing it. This includes both your mobile device and the Android simulator, which can lead to connectivity issues when developing locally. +::: + +##### Scenario 3: Run Prose Locally & Access from your Mobile Device + +It can be very useful to develop and debug against the app using your actual mobile device with the [Expo Go app](https://expo.dev/client). + +In order to do this, you'll need to have your development machine reachable from your mobile device. + +A simple way to make it reachable is to ensure that your mobile device and development machine are on the same network, and then, in `api/.env`, set `PROSE_APP_HOSTNAME` to `0.0.0.0`. + +In a regular Expo project, you would be required to update the `localDevelopment.proseUrl` value in `frontend/Config.ts` to contain the hardcoded IP address of your development machine on your network. + +However, by setting the value to `http://localhost`, we handle this **automatically** by default, so you don't have to worry about it. Read more about it [here](env-mobile#infer_development_host). + +###### Hardcoding your local IP Address + +:::info +This approach is not ideal. If your local IP address ever changes, you'll need to locate it again, and update `Config.ts` to reflect that. For this reason, it's preferable to just use `http://localhost`. +::: + +To manually instruct the Mobile App how to locate your development machine, you'll need to find out what the **local IP address** of your development machine is on your current network. + +Note that your local IP address is different from your public IP Address. + +If you are not sure how to get your local IP address, you can go to [What Is My Browser: Detect Local IP Address](https://www.whatismybrowser.com/detect/what-is-my-local-ip-address) and follow the instructions. + +The website itself may not be able to automatically detect your local IP address, but it will give you instructions on how to locate it within your specific operating system. + +You will be given an IP address like `10.0.12.121` or `192.168.17.69`. + +You can then update the value in `frontend/Config.ts` to your local IP address. + +This will allow the app running on your mobile device to properly locate the GraphQL API running on your development machine. + +## Configure your Discourse Host + +As mentioned above, you'll need to have setup a Discourse host for the GraphQL API to interact with. + +We'd like to briefly cover the different approaches to setting up a Discourse Host for development before continuing. + +**1. Run a Discourse Instance Locally** + +:::note +Ensure that you are managing all of your ports correctly. + +The development setup of Discourse with Docker makes use of multiple ports, one of which being **port 3000** by default. You'll want to double-check that none of the environment variables are pointing at the ports Discourse is using. +::: + +If you'd like to run a Discourse site for development locally, the recommended way to do this to use **[Docker](https://www.docker.com/)**, so make sure you have it installed. + +Then, as we mentioned above, you can follow [these steps in the tutorial](tutorial/setup-discourse) to install and run a development instance of Discourse in Docker. + +**2. Use try.discourse.org or another popular Discourse site** +:::info +Feel free to use existing public Discourse sites—such as the [Docker Community Forum](https://forums.docker.com/) or the [Rust Programming Language Forum](https://users.rust-lang.org/)—in order to test out the Lexicon Mobile App. + +Just be mindful of how you're contributing to those sites if you do. +::: + +[Try Discourse](https://try.discourse.org/) is a publicly accessible Discourse instance which is intended for testing. As such, it resets every day. + +The only drawback of this approach is that you can only register as a normal user, and therefore cannot modify the site's admin settings. + +With this approach, you'd simply configure Prose in `api/.env` to point `PROSE_DISCOURSE_HOST` at one of these instances. + +```bash +PROSE_DISCOURSE_HOST=https://try.discourse.org +``` + +## Working with the Codebase + +Now that you've prepared everything for development, you can start digging in on the Lexicon codebase. + +### Run the Lexicon Mobile App & Prose GraphQL Server + +You can run the Mobile App and test it out with a local Prose server by running this command **from the project root**: + +``` +$ npm run dev +``` + +This will simultaneously launch two processes: + +- The GraphQL API Server +- The local Expo dev server, which will enable you to launch the React Native app from your device + +However, if you wish to run the frontend and backend seperately, execute the following command in a terminal to run the frontend + +``` +$ npm run --prefix frontend start +``` + +Then execute the following line in another terminal to run the backend + +``` +$ npm run --prefix api dev +``` + +### Debugging + +- Use [Expo Developer Menu](https://docs.expo.io/workflow/debugging/#developer-menu) to make the debugging process easier. + +Opening the Expo Developer Menu depends on your device: + +- On an iOS Device: Shake the device, or touch 3 fingers to the screen. +- On the iOS Simulator: Hit `⌘ + ctrl + Z` on a Mac in the emulator. +- On an Android Device: Shake the device vertically, or run `adb shell input keyevent 82` in the terminal window if the device is connected via USB. +- On the Android Emulator: Hit `⌘ + M`, or run `adb shell input keyevent 82` in your terminal window. + +- If your changes don't show up, it could involve a cache issue. In this case, you should try restarting Expo. + - To do so, quit the process by hitting `Ctrl + C` in the Terminal where it is running. + - Then run `npm run start` again. + - If the issue persists, you should look for the latest guidance from Expo on how to clear the cache, as it has been known to change. + +### Running the Test Suites + +Before running tests, double-check that your changes don't contain any errors. + +You can run tests across both the frontend and backend codebases sequentially by running the following command from the project root: + +``` +$ npm run test +``` + +On top of ensuring that all tests have passed, the command will also notify you if there are any Typescript errors or issues from Prettier or ESLint. + +Also note that the process of running `npm run test` triggers an additional action in the frontend to take place before running the tests. + +A new folder, `frontend/generated`, is created and populated with all the GraphQL Query and Mutation types for use in the codebase. + +If we did not run this before the tests, they would fail due to type errors. + +### Build & Publish the Lexicon Mobile App + +:::note +An Expo account is required in order to use Expo's services. You can create one here: https://expo.io/signup. +Once you have created your Expo account, please ensure that you are signed in with your current shell session, via `expo login` or `eas login`. +::: + +You are required to configure EAS build first by running: + +```bash +eas build:configure +``` + +You will then get a prompt from the EAS CLI related to the EAS project IDs: `android.package` and `ios.bundleIdentifier`. EAS will provide you with an existing project ID if you have one or ask you to create a new one. As for `android.package` and `ios.bundleIdentifier`, you can specify those values with `com.companyname.appname`, or any other patterns you might prefer. + +Once you're done, verify the `proseUrl` value you will use for the actual build of the app in `Config.ts`. + +:::info +When publishing your app, it is necessary to deploy Prose somewhere publicly accessible, perhaps on a cloud hosting provider like AWS or DigitalOcean. If Prose is only running on your local machine, users that download your app won't be able to use it. +Check [the documentation](deployment) to deploy Prose if you haven't already. +::: + +Now you can build the Mobile App via Expo (EAS) with the preview build profile by running command below: + +```bash +eas build –platform all –profile preview +``` + +When you do this, the packager will minify all your code and generate two versions of your code—one for iOS, and one for Android—and then upload them both to the Expo CDN. + +Additionally, if you haven't yet optimized the app's assets, Expo will ask you if you'd like to do so. + +This has the same effect as manually running `npx expo-optimize` beforehand. It simply compresses all of the image assets in your project to reduce the size of your build. + +When the process is complete, you'll be presented with a shareable QR Code and a URL resembling https://exp.host/@ccheever/an-example, which directs you to the build details in Expo's web console. + +At this point, anyone can then use that link to load your project. + +For Android, you can install the app on an emulator or on your physical device. However, for iOS, you can only install it on the iOS simulator. To run the app on a real iOS device, follow the steps in [this part](tutorial/building#1-preview) of the tutorial. + +When building your app, it is recommended to build it as a preview build first, and make sure everything runs well before building it for release with the production profile. + +To build the app with the production build profile, run this command: + +```bash +eas build –platform all –profile production +``` + +You will also be presented with links directing you to the build details in Expo. + +However, unlike the preview build, the release build cannot be installed directly on your physical device or in an emulator / simulator. You'll need to publish the app and then install it from either the Play Store or App Store. + +You can read a more detailed explanation of this process in [this section](tutorial/building) of the tutorial. + +#### Updates + +If you later want to deploy an update to your version of the Lexicon Mobile App, you can use the EAS update command. + +First, make sure to configure EAS update by running the following command: + +```bash +eas update:configure +``` + +This command will automatically add the `expo.runtimeVersion` field to your `app.json` file. +You'll see a warning in your terminal telling you to add `expo.updates.url` to `app.json`. + +Then run this command to update your project: + +```bash +eas update -–branch +``` + +:::note +The channel name is the same as the build profile, so for the preview builds, you can run: + +```bash +eas update -–branch preview +``` + +::: + +Read more about updating your app [here](tutorial/updating). + +Once published, the new version will be available to your users the next time they open it. + +For more details on this process—including publishing to the App Store and Google Play Store—follow the instructions in [Publishing your App](tutorial/publishing). + +#### Configure the GraphQL API with your Discourse Server + +In order for a published version of the app to be able to contact your Discourse server, you'll need to ensure that: + +- The GraphQL API is deployed and running properly on a host that is reachable from the app itself. +- The GraphQL API is configured to point at the correct host and port of your Discourse server +- Your Discourse server is reachable by the GraphQL API diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/supported-devices.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/supported-devices.md new file mode 100644 index 00000000..148acbb7 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/supported-devices.md @@ -0,0 +1,29 @@ +--- +title: Supported Devices +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## iPhone and Android Phones + +Once you've published to the App Store and Google Play Store, your published app will work out of the box for your users on both iPhone and Android devices with the following specifications: + +| Device | Minimum OS | +| --------------- | ------------------- | +| iPhone | iOS 6 and above | +| Android Devices | Android 5 and above | + +| Android | iOS | +| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| | | +| | | +| | | +| | | + +## Support for Other Devices + +At this time, **tablets - including iPads** - and other mobile devices are **not supported**. + +We may consider developing support for this in the future. + +If this is critical for you, please drop us a line at support@kodefox.io and let us know. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/technologies.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/technologies.md new file mode 100644 index 00000000..c4180c4f --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/technologies.md @@ -0,0 +1,23 @@ +--- +title: Technologies +--- + +### 100% React Native and TypeScript built on Expo + +Lexicon was built, and is maintained, with a single code base—meaning that bug fixes, improvements, and new features will (in most cases) automatically apply to both iOS and Android. + +### GraphQL-based API + +Developers who wish to contribute to (or fork) Lexicon can do so with all the benefits of GraphQL. For more information, check out [Concepts and Architecture](concepts#prose-discourse-through-graphql). + +### White Labeling Support + +White Label the Lexicon Mobile App to give your users the familiar look and feel of your brand. Learn more in [White Labeling](white-labeling). + +### Painless integration with existing Discourse instances + +Getting started is as easy as spinning up a new server for the Prose GraphQL API, and pointing it at your Discourse instance. No changes are required on your Discourse instance itself. + +However, to provide an [optimal experience](optimal) with features like Tagging and Topic Excerpts, you will need to make some light adjustments. + +This is covered in detail in [Deploying Prose](deployment). diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/theming.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/theming.md new file mode 100644 index 00000000..04dbc172 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/theming.md @@ -0,0 +1,247 @@ +--- +title: Theming +--- + +:::note +This section will involve reading and modifying Typescript. If you get stuck, reach out to us. +::: + +Lexicon allows you to customize the default theme that the Mobile App provides. + +You can accomplish this by modifying the values in `frontend/src/constants/theme`, or in `frontend/src/theme`. + +There is a difference between the two, and they work in conjunction with one another. + +`frontend/src/constants/theme` defines the underlying base values of the theme. + +`frontend/src/theme` then imports those values, and uses them to compose the actual theme object used throughout the rest of the Mobile App. + +## Colors + +### Adjusting Base & Functional Colors + +There are 2 types of colors in the Mobile App: base colors and functional colors. + +Base colors are the underlying palette of the theme, whereas functional colors define specific use-cases of the base colors. + +For example, you might have noticed that the Mobile App features a nice, eye-catching Royal Blue color as its primary color. + +This is defined in the base colors as: + +```ts +// ... +royalBlue: '#2B6AFF', +// ... +``` + +Then, the functional colors make use of this for particular components in the app. + +To continue with the example, the `royalBlue` base color is referenced in the functional colors as: + +```ts +// ... +activeTab: BASE_COLORS.royalBlue, +// ... +primary: BASE_COLORS.royalBlue, +// ... +``` + +Now, any component can reference the functional colors' `primary` value, and it will be `royalBlue`. + +However, if you wanted a different theme with a new color, such as, `BASE_COLORS.lightningYellow`, then you could adjust it to: + +```ts +// ... +activeTab: BASE_COLORS.lightningYellow, +// ... +primary: BASE_COLORS.lightningYellow, +// ... +``` + +And the Mobile App would replace the Royal Blue with the value you've defined for Lightning Yellow. + +For this reason, if you want to add more colors, you'll need to add base color values first, and then access them within the functional colors. + +This approach keeps a clean separation of concerns, which allows theme changes to seamlessly propagate throughout the Mobile App. + +### Color Scheme (Dark Mode and Light Mode) + +The theme allows you to control how the user can adjust the app's color scheme, if at all. + +There are three choices for this: `dark`, `light`, `no-preference`. + +- Dark: force the color scheme to remain dark +- Light: force the color scheme to remain light +- No Preference (default): allow your users to specify a preference for color scheme + +Note that if you specify `dark` or `light`, your users **will not** have the option of selecting a preference for color scheme. + +This manifests in the Mobile App by hiding the Dark Mode button which normally appears in the Preferences Scene. + +## Fonts + +The theme's fonts are declared in `frontend/src/constants/theme/fonts`. + +Inside of that file, you'll find multiple aspects of the fonts that can be adjusted: + +- Font Variants +- Font Sizes +- Heading Font Sizes + +### Font Variants + +Used to classify multiple font weights into named variants. It supports the following values: + +| Variants | Default font weight | +| -------- | ------------------- | +| bold | 700 | +| semiBold | 600 | +| normal | 400 | + +### Font Sizes + +Used to set a font size scale that is consistent throughout the app. It supports the following values: + +| Variants | Default size | +| ---------------- | ------------ | +| xl (extra large) | 24 | +| l (large) | 18 | +| m (medium) | 16 | +| s (small) | 14 | +| xs (extra small) | 12 | + +### Heading Font Sizes + +Used to classify multiple font sizes for heading elements, such as `h1`, `h2`, etc. + +These values are primarily used for rendering the content of posts and messages from Discourse. + +This is because Discourse posts are written in Markdown, and users will often leverage heading elements to format their posts. + +| Variants | Default size | +| -------------- | ------------ | +| h1 (Heading 1) | 32 | +| h2 (Heading 2) | 24 | +| h3 (Heading 3) | 22 | +| h4 (Heading 4) | 20 | +| h5 (Heading 5) | 18 | +| h6 (Heading 6) | 17 | + +## Icons + +The `icons` theme file is used to store icon-related constants. + +Currently, the ‘icons’ file only contains a constant which declares the icon sizes scale. + +| Variants | Default size | +| ---------------- | ------------ | +| xl (extra large) | 28 | +| l (large) | 24 | +| m (medium) | 20 | +| s (small) | 18 | +| xs (extra small) | 16 | + +## Images + +The `images` theme file is used to store theme constants used in rendering images. + +Currently, this file declares the following theme values: + +- Avatar Icon Size +- Avatar Letter Size +- Avatar Image Size + +Avatars are used throughout the app to display relevant info about a post or message. + +As such, it is typically the user's photo. + +However, when a photo is not provided, we also compose a letter-based avatar based on the user's initials. + +### Avatar Icon Size + +| Variants | Default size | +| ---------------- | ------------ | +| l (large) | 96 | +| m (medium) | 52 | +| s (small) | 40 | +| xs (extra small) | 28 | + +### Avatar Letter Size + +| Variants | Default size | +| ---------------- | ------------ | +| l (large) | 72 | +| m (medium) | 36 | +| s (small) | 28 | +| xs (extra small) | 16 | + +### Avatar Image Size + +This defines the quality of the image used for avatars. + +| Variants | Default size | +| ---------------- | ------------ | +| xl (extra large) | 450 | +| l (large) | 150 | +| m (medium) | 100 | +| s (small) | 50 | + +## Spacing + +The `spacing` theme file defines spacing constants used throughout the Mobile App for padding and margins. + +| Variants | Default size | +| ------------------------- | ------------ | +| xxxl (triple extra large) | 36 | +| xxl (double extra large) | 24 | +| xl (extra large) | 16 | +| l (large) | 12 | +| m (medium) | 8 | +| s (small) | 4 | +| xs (extra small) | 2 | + +## Advanced Customization + +While the above adjustments are generally fairly simple, you can really customize the Mobile App to your heart's content (based on your skill level). + +Here are some additional aexamples. + +### Custom Fonts + +#### Create a folder for the Custom Fonts + +To keep the codebase organized, create a folder named `fonts` inside of `frontend/assets`. + +You can then move your custom font assets into this folder. + +#### Install & Use the `expo-font` Package + +This package eases the process of adding custom fonts into an Expo-based app. + +In particular, you'll want to use the `loadAsync` function from it, which will map your font assets to their variant names throughout the Mobile App. + +While we won't get into too much technical detail here, their [documentation](https://docs.expo.dev/versions/latest/sdk/font/) can guide you through the process. + +### Error Messages + +It is possible to customize both the error messages and the means through which they are presented to the user. + +In order to do this, you should first be aware of two files. + +#### `frontend/src/helpers/errorMessage.ts` + +The Prose GraphQL API forwards on error messages from Discourse. + +This file declares the specific text of those messages as constants so that they can easily be compared in `errorHandler.ts`. + +If you observe any additional error messages that are not being caught, you'll want to add them to this file, and then adjust `errorHandler.ts` below accordingly. + +#### `frontend/src/helpers/errorHandler.ts` + +This file imports from the above `errorMessage.ts`. + +It then defines exactly how errors should be handled, including the above messages, when they are encountered. + +Currently, the default approach is to display the errors using an Alert to the user. + +However, if you wanted to integrate snackbars, you would adjust the code in `errorHandler.ts` to replace the invocations of `Alert.alert`. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/troubleshooting-build.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/troubleshooting-build.md new file mode 100644 index 00000000..68d75dad --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/troubleshooting-build.md @@ -0,0 +1,128 @@ +--- +title: Troubleshooting when trying out the app +--- + + + + + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Troubleshooting Connection and Configuration Issues with URL + +
+ please connect to network error +
+ +If you are encountering issues related to the URL, resulting in an error message saying "please connect to network" as shown in the screenshot, it is likely due to incorrect settings. Specifically, if you are attempting to test builds locally on your mobile device and the channel field is not properly configured, the app may continuously fallback to the localDevelopment channel, even if you have set it to something else like "preview." + +Here some steps and notes to help resolve this: + +- Open the `frontend/Config.ts` file in your project. +- Locate the `config` object within the file. +- In the `localDevelopment` section of the `config` object, you can add the Prose URL specific to the channel you are trying to test. This section is used for local development and as a fallback configuration for unknown build channels in EAS Build. Here's an example: + + ```ts + const config: Config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, + }; + ``` + +- The example above shows that the config consists of two main sections: localDevelopment, which specifies the URL during localDevelopment, and buildChannels, which includes configurations for different channels such as preview and production. For local development, it will hit the Prose API with the URL `http://localhost:8929`. If the buildChannel is unknown or not found, it will always default to localDevelopment. +- Update the `proseUrl` value within the desired build channel, such as `preview` or `production`, with the valid and reachable URL of your Prose server. +- Once you have made the necessary changes, save the `frontend/Config.ts` file. + +Now, when you run eas build for a specific build channel, such as `eas build --profile=production`, it will utilize the Prose URL specified in the production configuration. + +:::note +It is important to include the URL in the `frontend/app.json` file, which expo-updates will use to fetch update manifests. Failing to set the URL in the `frontend/app.json` file will result in the expo-update constant always returning undefined for the channel, causing the app to consistently utilize the localDevelopment URL after building. You can specify this URL in the expo and updates sections of the app.json file. For more detailed information on how to configure this, please refer to the [expo documentation](https://docs.expo.dev/versions/latest/config/app/#url) for more detail on this. + +```json +"expo": { + "updates": { + ..., + "url": "https://u.expo.dev/" + } +} +``` + +This configuration is essential for seamless integration with Config.ts in your project. +::: + +In certain cases, you may encounter an issue related to Prose API URLs when the channel name specified in the `frontend/eas.json` file does not match the corresponding key name defined in the `config` variable in `frontend/Config.ts`. This discrepancy can lead to problems because the channel name from `eas.json` is used to determine the URL that will be utilized. If the names do not match, the default `localDevelopment` URL will be used instead. + +To ensure smooth functioning, it is important to use the same channel name in both the `frontend/eas.json` file and the `frontend/Config.ts` file. This will ensure proper mapping of the channel name to the corresponding URL. + +Here is an example to illustrate this: + +```json +// frontend/eas.json + +"build": { + "staging": { + "android": { + "buildType": "apk" + }, + "channel": "staging" + } +} +``` + +```ts +// frontend/Config.ts; + +const config: Config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + inferDevelopmentHost: true, + }, + + buildChannels: { + preview: { + proseUrl: '', + }, + production: { + proseUrl: '', + }, + staging: { + proseUrl: '', + }, + }, +}; +``` + +## The app closes abruptly after the splash screen + +If you encounter a situation where your app closes abruptly after the splash screen, it is likely that there are missing configurations in your `app.json` file. One common cause is the absence of a scheme definition in `app.json`, which is essential during the app build process. + +To resolve this issue, follow these steps: + +1. Open your project's `frontend/app.json` file. +2. Look for the `"expo"` section. +3. If a scheme is not present add this part in `"expo"` section + +```json +"expo":{ + "name": "", + "slug": "", + "scheme": "", + "version": "1.0.0" +} +``` + +Replace `""` with the desired scheme name for your app. + +4. Save the changes to the `app.json` file. +5. Rebuild your app and test it again. + +By ensuring that the scheme is correctly defined in `app.json`, you should be able to resolve the issue of the app closing after the splash screen. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/building.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/building.md new file mode 100644 index 00000000..3e261343 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/building.md @@ -0,0 +1,152 @@ +--- +title: Build your App +--- + +## EAS Build + +EAS Build is the upgraded version of `expo build`. This service helps to build app binaries for your Expo and React Native projects. Read more about it in the Expo documentation [here](https://docs.expo.dev/build/introduction/). + +### Configuration + +Let's get started by configuring EAS build. Check [here](https://docs.expo.dev/build-reference/build-configuration/) to see the complete guide from Expo. + +#### Build Setup + +Run this command in `/frontend` directory: + +```bash +eas build:configure +``` + +When running that command, the EAS CLI will typically do the following: + +1. It will prompt you for the EAS project ID, either to use an existing ID if you have one, or create a new one. Then it will automatically add the `expo.extra.eas.projectId` field in `app.json`. +2. It will create a new `eas.json` file if one doesn’t already exist. However, we have that set up for you, so you don't need to worry about creating one. 🎉 +3. It will prompt you to specify `android.package` and `ios.bundleIdentifier` if those values are not already provided in `app.json`. Note that those two values don't have to be the identical. + +You can see that the values in `app.json` are updated after running the command. + +#### Configuration Values + +:::info +When publishing your app, it is necessary to deploy Prose somewhere publicly accessible, perhaps on a cloud hosting provider like AWS or DigitalOcean. If Prose is only running on your local machine, users that download your app won't be able to use it. +Check [the documentation](../deployment.md) to deploy Prose if you haven't already. + +In the original release of Lexicon, the **Prose URL** was specified in `frontend/.env`. However, as part of migrating to Expo's EAS feature, we centralized the configuration into `frontend/Config.ts` to save you the trouble of needing to maintain it in more than one place, as suggested in the [Expo documentation](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update) +::: + +Next, open `Config.ts` and overwrite the placeholder values with the Prose URL you want to use for the build version. You can either set the same values or a different one for each channel. You don't need to adjust the values in `localDevelopment` since that is only used in development, and not when building the app. + +```ts +const config = { + // ... + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, +}; +``` + +### Run a Build + +#### Build for Both Platforms + +To build on both platforms, you can use either of the commands below: + +```bash +eas build --platform all +``` + +```bash +eas build -p all +``` + +#### iOS only + +```bash +eas build --platform ios +``` + +#### Android only + +```bash +eas build --platform android +``` + +#### Run a build with a specific profile + +```bash +eas build --platform all –-profile +``` + +```bash +eas build -p all –e +``` + +:::note +Without --profile, the EAS CLI will default to the `production` profile. +::: + +### Build Profiles + +Build profiles serve as a way of grouping configuration values for different scenarios when building the mobile app. + +You can find more details [here](https://docs.expo.dev/build/eas-json/). + +The `eas.json` file can contain multiple build profiles. However, it typically has 3 profiles: **preview**, **development**, and **production**. + +#### 1. Preview + +Purpose: to internally test the app in production-like circumstances. + +It is recommended to try building with the preview profile **_first_** before building your app with the production profile. That way, you can ensure the app runs as expected before it’s ready to be published. + +The build type for Android will be an **APK** file, whereas the iOS build will output a format that can be installed on the simulator. + +This is because the `ios.simulator` option was specified in `eas.json`: + +```json + "ios": { + "simulator": true + }, +``` + +If you want to run the preview build on a real device, you'll need have an Apple account with Apple Developer Enterprise Program membership, then add the `ios.enterpriseProvisioning` value in `eas.json`: + +```json + "ios": { + "enterpriseProvisioning": "universal" + } +``` + +For the `preview` build profile, we have already set the distribution mode to [internal](https://docs.expo.dev/build/internal-distribution/). This ensures that EAS build provides shareable URLs for builds, with instructions on how to get them running. + +This approach then allows us to test the app without submitting to the App Store or Play Store. + +#### 2. Development + +Purpose: to make debugging easier. Expo will automatically include developer tools in the build. As you may have figured, this build should never be published to either of the app stores. + +Development builds depend on [expo-dev-client](https://docs.expo.dev/development/introduction/), so Expo will prompt us to install the library if needed. + +Similar to preview builds, you can add the iOS options mentioned above to run them on a simulator or real device. + +#### 3. Production + +Purpose: for submission to the App Store and Play Store—as a public release, or as part of testing in each respective ecosystem. + +In order to use builds like this, they must be installed through the respective app stores. + +After running builds with this profile, you'll see that the iOS and Android versions have automatically been incremented. As you might expect, this is because `autoIncrement` has been set to `true`. + +It is worth noting, however, that this behavior only applies to TestFlight and Internal Testing, so you'll need to be sure to also manually increment the `expo.version` in `app.json` for public release. Expo provides further [documentation](https://docs.expo.dev/build-reference/app-versions/) on this topic. + +## The App is Built + +Great work! You can now share the installation link with your peers so they can try out the app. + +In the next section, you'll learn how to [publish](publishing) your app to the App Store and Play Store! 🚀 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/install-prose.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/install-prose.md new file mode 100644 index 00000000..d6ecec67 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/install-prose.md @@ -0,0 +1,360 @@ +--- +title: Setup the Prose GraphQL API +--- + +Now that we have a running Discourse instance to interact with, we can move onto setting up the Prose GraphQL Server. + +To recap, Prose is a part of the Lexicon stack. + +It is responsible for providing a [GraphQL](https://graphql.org/) interface on top of Discourse, which the Lexicon Mobile App can then interact with. + +For more information about this, check out [Concepts & Architecture](../concepts). + +## Approaches for Setting Up Prose + +If your Discourse instance is running locally, it is natural that you should also setup your Prose server locally. + +Otherwise, it would be unnecessary extra work to get a remote Prose server communicating with your local Discourse server. + +However, if you've setup your Discourse instance in the cloud, it is up to you if you want to run your Prose server locally or in the cloud as well. + +If you'd like to install it in the cloud, you'll want to setup an additional server - similar to how you would set one up for Discourse. If you're not yet comfortable with this, feel free to jump back to the page, [Setup a Cloud Server (Optional)](setup-cloud-server). + +Bearing all of that in mind, once you have identified where you'd like to host Prose, you should also consider how you'd like to install it onto that machine. + +The first way, which we recommend, is to use **[Docker](https://www.docker.com/)**. + +And of course, the second way is to install it manually, rather than using containers. + +## Install Prose using Docker + +The reason we recommend using Docker is because you won't have to worry about setting up Prose's on your machine. + +We have already published Prose to [Docker Hub](https://hub.docker.com/), which means you can easily pull it down and run it. We'll guide you through that below. + +### Install Docker + +First, just as was necessary for setting up Discourse, you'll want to make sure Docker is installed on your machine. + +You can follow the instructions on the [Docker installation page](https://www.docker.com/get-started) if you are unsure of how to do this. + +### Pull and Run the Prose GraphQL API Image + +After successfully installing Docker, you can use the command below to run the Prose GraphQL image. + +Just bear in mind that you'll want to adjust some of the **environment variables** to your situation before you run the command. + +``` +$ docker run -d \ + -e PROSE_DISCOURSE_HOST=https://meta.discourse.org \ + -e PROSE_APP_PORT=80 \ + -p 5000:80 \ + --name prose-graphql \ + kodefox/prose +``` + +The above command will take care of pulling the Prose GraphQL Docker Image, building it, and running it in a container. + +To help understand everything that's going on there, let's break it down line by line. + +```bash +docker run -d +``` + +This instructs Docker to run our image as a container in **detached mode**. This is similar to backgrounding a process. + +```bash +-e PROSE_DISCOURSE_HOST=https://meta.discourse.org +-e PROSE_APP_PORT=80 +``` + +The `-e` flag instructs Docker that we want to set or override certain environment variables in the container with the values we provided. + +In this case, we're telling Prose to interact with the Discourse instance is running at `https://meta.discourse.org`, and that Prose should run itself _inside of the container_ on a port of `80`. + +``` +-p 5000:80 +``` + +Next, we're telling Docker what ports we want to map from our host machine into the container. + +In the previous step, we established that Prose will run internally on port 80. With the above command, we're telling Docker to expose the container's port 80 as port 5000 on our host. + +This means that Prose will be reachable on port 5000 of the host. + +So, if you're running this locally, you'll be able to interact with Prose at `http://localhost:5000`. + +And if you're running it in the cloud on a domain like `https://prose.mydiscussions.com`, you'd likely want it to be listening on port 443 so the user doesn't have to enter a port number as part of the URL. + +### Configure Prose + +As suggested above, you can configure Prose through the use of environment variables. + +You can find a comprehensive list of all environment variables on the Prose [Environment Variables](../env-prose) page. + +In this case, you really only need to set a value for `PROSE_DISCOURSE_HOST`, which will instruct Prose which Discourse instance you'd like it to interact with. + +Additionally, if you'd like to set a different port mapping, you can adjust the `-p` flag of the `docker run` command to something else, such as: + +```bash +-p 8080:80 +``` + +## Install Manually + +This section, whether being done locally or remotely on a cloud provider, will require you to install and configure the necessary dependencies to build and run Prose from scratch. + +### Setup Development Machine + +If you haven't already, setup your machine for Prose development. You can do so by following the guide at [Setup your Development Machine](setup). + +By the time you're done with this step, you should have a local copy of the Lexicon repository on your desired machine. + +### Configure Environment Variables + +The Prose GraphQL API, at a bare minimum, requires you to provide a URL to an accessible Discourse instance in order to run properly. + +Because we're doing this manually, you'll need to specify this in a different way than you would for Docker. + +Later on, once you've built Prose, one way you can specify this is to simply provide it inline as you launch the server. + +```bash +PROSE_DISCOURSE_HOST=https://discourse.mysite.com node lib/index.js +``` + +However, you might find it more ergonomic to leverage the support we've setup for `.env` files. + +The entire Prose codebase lives in the `api/` directory of the repository, so get started by navigating there from the project root. + +``` +$ cd api/ +``` + +Next, you'll need to create a `.env` file. Simply copy the template file, `.env.example` into the `.env` file using the following command. + +``` +$ cp .env.example .env +``` + +After that, as you'd expect, you want to adjust the `.env` file so that it contains the values specific to your project. + +```bash +PROSE_DISCOURSE_HOST= +PROSE_APP_PORT= +``` + +As was covered in the Docker section above, you can find a comprehensive list of all environment variables on the Prose [Environment Variables](../env-prose) page. + +### Launch the Prose GraphQL API + +:::info +At this point, you should already have all the project's dependencies installed. + +If you encounter any errors about missing packages, go back to the guide at [Setup your Development Machine](setup). +::: + +If you'd just like to launch Prose to check it out quickly, you can simply run (from the `api/` directory): + +```bash +$ npm run dev +``` + +This will prepare and spin up Prose in a way that isn't ideal for production. + +If you wish to run the Prose GraphQL API in the background as a process, there are multiple solutions. + +One method is to use **[Tmux](https://github.com/tmux/tmux)**, which will detach the process from the terminal, allowing you to close it and keep Prose running. + +Another method is to use **[PM2](https://pm2.keymetrics.io/)**, which is a sophisticated toolset for running Node processes in production. + +#### Using Tmux + +**Tmux** can be used to detach processes from their controlling terminals, allowing sessions to remain active without being visible. + +To get started, install `tmux` on your machine. + +If you are unsure of how to install tmux, you can follow the instructions on [this page](https://github.com/tmux/tmux#installation). + +Once it's installed, launch it as follows: + +```bash +$ tmux +``` + +Then you can run Prose in the same way as before. + +```bash +$ npm run dev +``` + +If you want to detach from your current session, press `Ctrl + B` then press `d` on your keyboard. The session will remain active in the background. + +And if you wish to re-attach to your last session, run the following command. + +``` +$ tmux a +``` + +If you want to learn more about the tmux command, check out [this cheat sheet](https://tmuxcheatsheet.com/). + +#### Using PM2 + +Another way to run Prose in the background is to use **pm2** (process manager for NodeJS). + +First, as you'd expect, you'll need to install `pm2` on your machine. + +``` +$ npm install -g pm2 +``` + +Once it's installed, you'll also need to use `pm2` to install [Typescript](https://typescriptlang.org/). + +This is because Prose is written in Typescript, and this allows PM2 to run the Typescript files directly for us (as opposed to transpiling them and outputting them as JS first). + +To do this, simply run the following command: + +``` +$ pm2 install typescript +``` + +After that, you can now launch the Prose GraphQL API in the background with: + +``` +$ pm2 start src/index.ts +``` + +To list all running applications, run the following command. + +``` +$ pm2 list +``` + +These are some of the frequently used commands. + +``` +$ pm2 stop # To stop a process +$ pm2 restart # To restart a process +$ pm2 delete # To delete a process +``` + +## Test the GraphQL API + +Now that you've successfully launched Prose, you can actually interact with it in your web browser. + +Because of the libraries that we leveraged in building Prose, it automatically comes with [GraphiQL](https://www.graphql-yoga.com/docs/features/graphiql). + +This is an in-browser GraphQL IDE that makes it easy to explore the documentation and the schema of the GraphQL API. + +In order to access it, you'll need to make note of the host and port number that you configured the API with. + +For example, if you launched Prose from your local machine on port 5000, you'd navigate to [http://localhost:5000](http://localhost:5000). + +Similarly, if you set it up in the cloud, and all you have is an IP address with Prose listening on port 80, you would navigate to something like [http://174.31.92.1](http://174.31.92.1). + +Once the [GraphiQL](https://www.graphql-yoga.com/docs/features/graphiql) interface loads, you can test out some example queries and mutations, including logging into Discourse through Prose. + +### Login + +:::info +If you're accessing a private Discourse site, you'll need to make note of the token that is returned to make other requests. See below. +::: + +``` +mutation Login { + login(email: "user@lexicon.com", password: "user_password") { + ... on LoginOutput { + token + user { + id + name + username + avatarTemplate + } + } + } +} +``` + +As mentioned in the notice, if you're interacting with a private Discourse site, you'll need to provide a token for other GraphQL requests. + +As part of the response for the above mutation, you'll notice a "token" field which contains your authentication token in Base64. + +You use this token in other queries and mutations by opening the HTTP Headers section on the bottom left-hand side of the page. + +This section expects JSON, with which you'll want to add an Authorization header that contains your token. + +```json +{ + "Authorization": "" +} +``` + +Once you have done that, you can make authenticated GraphQL queries and mutations as the user you logged in with. + +### User Profile + +``` + query UserProfile { + userProfile(username: "john_doe") { + user { + ... on UserDetail { + id + avatarTemplate + username + name + websiteName + bioRaw + location + dateOfBirth + email + } + } + } + } +``` + +### Topic Detail + +``` +query TopicDetail { + topicDetail(topicId: 1) { + id + title + views + likeCount + postsCount + liked + categoryId + tags + createdAt + postStream { + posts { + id + topicId + userId + name + username + avatarTemplate + raw + createdAt + } + stream + } + details { + participants { + id + username + avatarTemplate + } + } + } +} +``` + +### Logout + +``` + mutation Logout { + logout (username: "john_doe") + } +``` diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/intro.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/intro.md new file mode 100644 index 00000000..54e0d630 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/intro.md @@ -0,0 +1,45 @@ +--- +title: Overview +slug: /tutorial +--- + +## Welcome to the Lexicon Tutorial + +We're really excited to help you dig in with the Lexicon Stack and learn how to deploy it in a way that benefits you and your users. + +## Target Audience & Prerequisites + +In order to complete this tutorial, you should have familiarity with: + +- The command-line +- Git and Github +- Setting up a Discourse instance +- Setting up servers in general + +In terms of prepararation, you will need: + +- NodeJS installed on your development machine + - Use the latest version of Node that is compatible with the project's version of Expo (i.e. `expo-cli`). +- An editor to edit config files + +#### Have some concerns? + +Interested in Lexicon but lacking in technical abilities? We completely understand. + +Reach out to us at support@kodefox.com to chat about how we can help bring your idea to life. + +## Next Steps + +This tutorial will guide you through the process of getting the entire Lexicon Stack up and running **locally** with your Discourse site. + +At the end of the tutorial, you will be able to interact with your Discourse site in the Lexicon Mobile App on your local device or simulator. + +You will also have an understanding of: + +- How to configure and run the Prose GraphQL API locally or on a server you own +- How to configure and run the Lexicon Mobile app on your device or in a simulator +- The next steps needed to make full use of Lexicon + +Please note that this tutorial will not cover the process of actually launching the app, as well as certain details about deploying to production. For support with those tasks, please refer to the documentation. + +Let's get started! diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/publishing.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/publishing.md new file mode 100644 index 00000000..66005bdd --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/publishing.md @@ -0,0 +1,97 @@ +--- +title: Publish your App +--- + +## EAS Submit + +EAS Submit is a service for uploading and submitting your application binaries to App Store and/or Play Store. +Check [here](https://docs.expo.dev/submit/introduction/) to learn more about EAS Submit. + +### Prerequisites: + +- Registered app in App Store Connect, see the guide [here](../app-store#register-a-new-bundle-id). +- Registered app in Play Store, see the guide [here](../play-store). + +### Configuration + +Before submitting, you are required to specify the credentials to publish your app. + +#### iOS + +For iOS, fill in your account information for `appleId`, `ascAppId`, and `appleTeamId`: + +```json + "base": { + "ios": { + "appleId": "", + "ascAppId": "", + "appleTeamId": "" + }, + ... + }, +``` + +- **appleId**: your apple ID (e.g., `john@gmail.com`). +- **ascAppId**: your App Store Connect app ID. Find your ascAppID by following [this guide](https://github.com/expo/fyi/blob/main/asc-app-id.md) (e.g., `1234567890`). +- **appleTeamId**: You can check your apple team ID [here](https://developer.apple.com/account/) (e.g., `12LE34XI45`). + +#### Android + +For Android, you will need to add a `.json` key file to authenticate with the Google Play Store. Please follow [this guide](https://github.com/expo/fyi/blob/main/creating-google-service-account.md) to generate one. Then, copy the JSON file to your `lexicon/frontend` directory, and rename the file as `playstore_secret.json`. + +The JSON file looks like this: + +```json +{ + "type": "service_account", + "project_id": "", + "private_key_id": "", + "private_key": "-----BEGIN PRIVATE KEY----------END PRIVATE KEY-----\n", + "client_email": "", + "client_id": "", + "auth_uri": "", + "token_uri": "", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/lexicon%40api.iam.gserviceaccount.com" +} +``` + +Now that the configuration is done, you can start submitting your app. + +### Submitting + +Use this command to submit the build: + +```bash +eas submit --platform ios --profile +``` + +Then you will see the EAS CLI prompt asking which app you would like to submit. + +There are 4 possible options: + +- Selecting a build from EAS +- Providing the URL of an app archive +- Providing the local path to an app binary file +- Providing the build ID of an existing build on EAS + +If you have built your app using EAS Build or have been following the tutorial from [Build your App](building), then please choose the first option, and select the version you want. + +### Submit Profiles + +By default, `eas.json` has been configured with two submit profiles, which are **staging** and **production**. + +The configuration is mostly the same, the only difference lies in the Android track options. + +- Staging infers the track as `internal`. This means submitting with the staging profile will submit the build for internal testing in the Play Store. +- Production infers the track as `production`, which will submit the build for Public Release in the Play Store. + +With iOS, on the other hand, both profiles will be submitted to TestFlight before you can release them publicly. + +You can reference the Expo documentation to learn more about [Android-specific](https://docs.expo.dev/submit/eas-json/#android-specific-options) and [iOS-specific](https://docs.expo.dev/submit/eas-json/#ios-specific-options) options. + +## Congratulations! + +Your app is now available for users to download from both the Play Store and the App Store! 🥳 + +To learn more about how to update your published app in the case of a bug, as well as OTA updates, check out the [next and final section](updating) of the tutorial. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-cloud-server.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-cloud-server.md new file mode 100644 index 00000000..b69659a4 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-cloud-server.md @@ -0,0 +1,27 @@ +--- +title: Setup a Cloud Server (Optional) +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +:::info +This is an optional section for users that don't feel as confident spinning up a new server with a cloud provider. + +If you are already adept at this, you can skip to the next section. +::: + +## DigitalOcean Guide + +### How To Set Up an Ubuntu 20.04 Server on a DigitalOcean Droplet + +For our users that aren't as familiar with setting up servers in the cloud, we wanted to provide you with a solid resource to learn more about it and accomplish something in the process. + +DigitalOcean has already provided an excellent guide to walk you through this, so we're going to link you over to them. + +In this guide, you will create an Ubuntu server through DigitalOcean’s administrative panel and configure it to work with your SSH keys. + +Once you have a solid understanding of how to setup servers in the cloud, you'll be much more capable of deploying the Lexicon Stack for your users. + +You can dig in on the article below. + +[Read: How To Set Up an Ubuntu 20.04 Server on a DigitalOcean Droplet](https://www.digitalocean.com/community/tutorials/how-to-set-up-an-ubuntu-20-04-server-on-a-digitalocean-droplet) diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-discourse.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-discourse.md new file mode 100644 index 00000000..9b5bf97a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-discourse.md @@ -0,0 +1,306 @@ +--- +title: Prepare a Discourse Instance +--- + +Before you can properly setup Lexicon, you'll need to have a running **[Discourse](https://www.discourse.org/)** instance for Lexicon to interact with. + +For this step, you actually have a few options: + +#### Option 1: Setup a Local Discourse Instance + +The first option is to [setup a development instance](#setup-discourse-locally) of Discourse locally on your development machine. This takes a bit of time and can get a bit technical. + +#### Option 2: Buy a Discourse Instance or Use your Existing One + +The second option is to pay to [setup a Discourse instance in the cloud](#setup-discourse-in-the-cloud) as a live, reachable production verison. This is much simpler, but has the obvious tradeoff of costing money. + +And perhaps it goes without saying, but if you already have a Discourse site, feel free to just use that. + +#### Option 3: Use a Public Discourse Site + +The third option is to use an existing Discourse site just to test things out. + +As you'll see later on, Lexicon allows you to configure which Discourse site it is pointing at. As such, you can instruct it to point at at a publically accessible Discourse site that you don't personally own. + +There are countless examples of active Discourse communities out there. Here are a few examples to choose from: + +##### Discourse Meta + +[https://meta.discourse.org/](https://meta.discourse.org/) + +##### Expo + +[https://forums.expo.dev/](https://forums.expo.dev/) + +##### The Rust Programming Language + +[https://users.rust-lang.org/](https://users.rust-lang.org/) + +##### FreeCodeCamp Forums + +[https://forum.freecodecamp.org/](https://forum.freecodecamp.org/) + +## Setup Discourse Locally + +:::note +This section can take a long time. Depending on the specs of your machine, it could take between 10 - 30 minutes to complete. +::: + +This section of the tutorial is based on the following post on Discourse: [Beginners Guide to Install Discourse for Development using Docker](https://meta.discourse.org/t/beginners-guide-to-install-discourse-for-development-using-docker/102009). + +If you run into any issues, feel free to reference the original post and subsequent discussion. + +### Install Docker + +**[Docker](https://www.docker.com/)** is a containerization framework that makes it easy to build, manage, and deploy your application stack in a way that is safer, more reliable, and repeatable across multiple platforms. + +When developing, building, and testing applications locally, it is an invaluable tool that greatly simplifies the entire process. + +The main way that Docker helps us in this tutorial is that it won't require any modifications to our machine's environment other than installing Docker itself. + +This is as-opposed to needing to install all of Discourse's dependencies on your physical machine, in a way that may take a lot of effort to undo later. + +If you are unsure of how to install Docker, you can follow the instructions on their [website](https://www.docker.com/get-started). + +### Clone Discourse + +Once Docker is up and running, we can get started with setting up Discourse locally. + +The first step is to clone the Discourse repository to your local machine and `cd` into it. + +``` +git clone https://github.com/discourse/discourse.git +cd discourse +``` + +Note the repository is on the larger side (nearly 400mb), so this step may take a while depending on your connection. + +### Pull, Build, and Start the Discourse Dev Container + +:::caution +Make sure that the **host ports** listed below are not already in use on your device. +::: + +Discourse already contains a script to help spin up its entire infrastructure using Docker. + +During this process, the script will do the following: + +- Pull down the necessary "dev" Docker image to bootstrap Discourse +- Build the aforementioned image +- Run the image as a container with multiple ports mapped from your host into the container + - 127.0.0.1:**1080**->1080/tcp + - 127.0.0.1:**3000**->3000/tcp + - 127.0.0.1:**4200**->4200/tcp + - 127.0.0.1:**9292**->9292/tcp + - 127.0.0.1:**9405**->9405/tcp +- Prompt you for an admin email address and password + +To get started, simply run the following command: + +``` +$ d/boot_dev --init +``` + +Note that all of the Docker images add up to about 1GB of disk space usage on your device. + +The command will pause when it needs information from you. As shown below, it will prompt you for an administrator email address and password. + +```bash +# Output omitted +== 20200804144550 AddTitleToPolls: migrating ================================== +-- add_column(:polls, :title, :string) + -> 0.0014s +== 20200804144550 AddTitleToPolls: migrated (0.0021s) ========================= + +Creating admin user... +Email: me@me.com +Password: +Repeat password: + +Ensuring account is active! + +Account created successfully with username me +``` + +Next, it will ask you if you want to make this account an admin account. You do. + +```bash +Do you want to grant Admin privileges to this account? (Y/n) y + +Your account now has Admin privileges! +``` + +Please be aware, as suggested above, that the ports mentioned above are not currently in use by other processes. + +### If something unexpected happened + +It's possible that something strange may have happened at this step. + +Perhaps there was a weird error message, or the process just never displayed the output shown above. + +What we'd recommend doing is the following: + +#### Check if a Docker container named `discourse_dev` is running + +```bash +$ docker ps | grep discourse_dev +CONTAINER ID IMAGE ... NAMES +dc72a4ead10f discourse/discourse_dev:release ... discourse_dev +``` + +If it is, stop and remove the container. + +```bash +$ docker stop discourse_dev +discourse_dev +$ docker rm discourse_dev +discourse_dev +``` + +#### Exit or Kill the Existing Process + +If the existing process (`d/boot_dev --init`) is still occupying your terminal session, attempt to exit it via `Ctrl + C`. + +If the process is not responding to `Ctrl + C` after some time, locate its PID and use `kill -9` to kill it + +```bash +$ ps aux | grep rails +user 81254 0.0 0.1 discourse_dev bin/rails s + +$ kill -9 81254 +``` + +#### Restart Docker or your Machine + +Using the command or interface appropriate for your machine, you should restart all of Docker. + +On Docker for Mac, this is as simple as going into the tray icon and clicking Restart. + +#### Try running the command again + +Sometimes things just go a little haywire with this setup. Try running the command again to see if it works better this time. + +#### If you're absolutely stuck, reach out. + +Don't hestitate to contact us if you're just stuck with this one. + +### Optional: Run the Next Two Commands in the Background + +You can read on to get an understanding of what the two commands are, but it's worth mentioning that you want them to run simultaneously. + +You can do this by _backgrounding_ both processes. + +This means that they won't occupy your current session, requiring you to quit them in order to enter other commands. + +When you run this command, it will show you the process IDs (PIDs) of the processes that were backgrounded. + +To bring them back into the foreground, you can run the `fg` command, and then use `Ctrl + C` or a similar signal to stop them. + +```bash +d/rails s & d/ember-cli & +[2] 59786 +[3] 59787 + +fg +``` + +Just **note** that you won't see the output of the commands, and so you may need to be patient for several minutes until Discourse is reachable at its local address. + +Alternatively, you can use the PIDs to kill the processes outright in another session: + +```bash +kill -9 59786 59787 +``` + +### Start the Rails Server within the Container + +If you hadn't already noticed, Discourse is built in [Ruby](https://www.ruby-lang.org/en/) using the very popular web framework, [Ruby on Rails](https://rubyonrails.org/). + +By running the command below, you will be starting the Rails server, which will take some time, and will produce a tremendous amount of output. + +In particular, you'll see the database being initialized as the dev container bootstraps the Discourse server. + +To get started, simply run the following command. + +``` +d/rails s +``` + +#### If you later can't quit the process + +**Note** that this command can sometimes hang when you're trying to kill it with `Ctrl + C`. + +If that happens, it's recommended that you first stop the Docker container: + +```bash +docker stop docker_dev +``` + +Then, bring the process to the foreground with `fg` if necessary. + +Last, either exit your session if possible - such as by closing the Terminal - or find out the PID of the Rails process and kill it directly. + +```bash +$ ps aux | grep rails +user 81254 0.0 0.1 discourse_dev bin/rails s + +$ kill -9 81254 +``` + +### Run the Ember CLI + +The above section mentioned Ruby on Rails, which handles the backend aspects of the Discourse application. + +However, the Discourse frontend is build in [EmberJS](https://emberjs.com/), which is a batteries-included frontend web framework used by multiple major companies. + +Run the command below to instruct the Ember CLI to start the Discourse frontend. + +``` +d/ember-cli +``` + +Once you have done this, you'll be able to access Disourse at [http://localhost:4200](http://localhost:4200). + +Please note that the output of this command can be a bit confusing. And at times, it can seem like nothing is happening. + +You may see several progress indicators, as well as blank output, for several minutes before the server is ready. + +The output you're looking for will resemble the following: + +```bash +Build successful (72475ms) – Serving on http://localhost:4200/ + +Slowest Nodes (totalTime >= 5%) | Total (avg) +----------------------------------------------------------------------+------------------ +Babel: discourse (2) | 31501ms (15750 ms) +ember-auto-import-analyzer (11) | 10418ms (947 ms) +Bundler (1) | 6119ms +Babel: @ember/test-helpers (2) | 5075ms (2537 ms) +broccoli-persistent-filter:TemplateCompiler (3) | 4596ms (1532 ms) +``` + +## Setup Discourse in the Cloud + +There are several guides with instructions on how to setup Discourse in the Cloud. + +Rather than writing another one, we have found our favorite one and would like to send you over to them to give you a proper walkthrough of the process. + +### Guide by SSDNodes + +The guide is provided by the [SSDNodes](https://www.ssdnodes.com/?e=blog&q=more-about-ssdnodes) Blog, [Serverwise](https://blog.ssdnodes.com/blog/). + +If you aren't familiar, [SSDNodes](https://www.ssdnodes.com) is an excellent, cost-effective VPS hosting provider. + +While we are most familiar with Digital Ocean, we'd strongly encourage you to check them out as an alternative for hosting Discourse. + +The post, titled [How To Install Discourse On Ubuntu](https://blog.ssdnodes.com/blog/install-discourse/), is written by [Joel Hans](https://blog.ssdnodes.com/blog/author/joel/). + +Joel has written an excellent guide. He'll take you through the entire process, including making update to your Discourse instance. + +If you find yourself stuck, or have any questions, feel free to reach out to us. + +## Use a Public Discourse Site + +If you've chosen this option, there's not much to do other than to note the URL of the Discourse site you'll be using. + +Once you have that written down somewhere, you're ready for the next section. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-mobile.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-mobile.md new file mode 100644 index 00000000..62ab943a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup-mobile.md @@ -0,0 +1,120 @@ +--- +title: Configure & Launch the Mobile App +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +After following the **[Setup the Prose GraphQL API](install-prose)** section, your GraphQL API should now be connected to your Discourse site. + +Next, we'll guide you through the process of connecting the Lexicon Mobile App to your Discourse site via Prose. + +### Mobile App Configuration + +:::note +In the original release of Lexicon, the **Prose URL** was specified in `frontend/.env`. However, as part of migrating to Expo's EAS feature, we centralized the configuration into `frontend/Config.ts` to save you the trouble of needing to maintain it in more than one place, as suggested in the [Expo documentation](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update) +::: + +Before launching your local version of the Lexicon Mobile App, you'll need to configure it with at least one piece of information. + +The Lexicon Mobile app relies exclusively on a running instance of the Prose GraphQL API in order to retrieve data from your Discourse instance. + +Therefore, you'll need to instruct it on how to locate your running Prose server. + +In development, it is common to have it running locally. However, if you have already deployed Prose +somewhere, feel free to use that. + +#### Configuring `proseUrl` via `config` + +:::caution + +##### `proseUrl` requirements + +It is worth noting that `proseUrl` **must** start with either `http://` or `https://`. + +If it does not, the Mobile App will throw an error when launching. +::: + +`Config.ts` contains the `config` object, which allows you to specify the Prose URL for each scenario encountered when developing and building the Mobile App. + +The specific configuration value which enables this is `proseUrl`, and it is contained within each scenario expressed by the `config` object. + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com:8080/subpath', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +As mentioned earlier—above, the `config` object allows us to express configuration values for multiple scenarios, which are: + +- `localDevelopment`: when developing against the app locally. This configuration is also used as a fallback for an unknown build channel. +- `buildChannels`: used to define configuration by build channel when building the app with the EAS CLI. + +`buildChannels` makes use of Expo's build channels (typically `preview` and `production`) as its keys. + +Each key within `buildChannels` maps to a specific Prose URL, which will be used for the build version based on which channel you build for. + +From the example above, when we create a `preview` build, the app will be built and configured to contact a Prose server located at `https://preview.myserver.com:8080/subpath`. + +The example above expresses a setup in which each build has its own deployed Prose server. However, it is also common to use one server for all scenarios, including development. + +```ts +const config = { + localDevelopment: { + proseUrl: 'https://myserver.com/api/prose', + }, + buildChannels: { + preview: { + proseUrl: 'https://myserver.com/api/prose', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +##### Port Number + +Bear in mind that if your Prose server is not running on port 80 or 443, you also need to specify the **port number** via `proseUrl`. + +For example, if you've started a Prose server **locally** on port `8929` and try to run it using `expo start`, your `Config.ts` file would contain `http://myserver.com:8929/api/prose` under `localDevelopment.proseUrl`. + +### Launch the Mobile App + +Once you have configured everything, you'll want to launch the Mobile App to test that it is speaking to the right Prose server. + +To do this, you can simply run the following from the project root: + +```bash +npm run --prefix frontend start +``` + +The Expo development server should launch, and you can follow the instructions to run the app in a simulator or on your actual device. + +#### Troubleshooting + +If the app throws an error upon loading, you should double-check the configuration values you specified, according to the message you've received. + +If the app loads, but you're unable to actually connect, you should verify the following: + +- Your Prose Server is up and running at the location you provided to the Lexicon Mobile App +- Your Prose Server is configured to point at an accessible Discourse instance +- Your Discourse instance is up and running correctly + +## Nice Work! + +At this point, you've already accomplished a lot. + +The Discourse server you started off with is now accessible in a new way from a sleek native mobile app, and you're free to customize it to your heart's content. + +In the next part of the tutorial, we'll briefly get into that very topic: customizing the Mobile App to [white label](white-label) it for your brand. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup.md new file mode 100644 index 00000000..20505940 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/setup.md @@ -0,0 +1,98 @@ +--- +title: Setup your Development Machine +--- + +## Install NodeJS + +If you haven't already, install NodeJS on your machine. + +The tooling needed to setup Lexicon relies heavily on Node and npm. + +If you are unsure of how to install NodeJS, you can follow the instructions on the [NodeJS Website](https://nodejs.org/en/download/). + +#### Supported Node Versions + +It is recommended that you perform this tutorial using the latest version of Node that is compatible with the the project's version of Expo. + +You can always confirm this by viewing the dependencies in [frontend/package.json](https://github.com/lexiconhq/lexicon/blob/master/frontend/package.json). + +If your setup doesn't allow you to easily change your current Node version, we would recommend making use of [`nvm`](https://github.com/nvm-sh/nvm) to quickly switch between Node versions. + +### Install yarn, if you prefer + +Lexicon doesn't leverage any special features of [Yarn](https://yarnpkg.com/) - the alternative package manager for Node. If you prefer it, it will work the same as running `npm install`. + +For the purposes of this tutorial, we will demonstrate all commands using `npm`. + +### Clone the Lexicon Repository + +In a desirable location on your development machine, clone the Lexicon repository and `cd` into it. + +```sh +git clone git@github.com:lexiconhq/lexicon.git +cd lexicon +``` + +### Install Dependencies + +Next, install Lexicon's dependencies: + +```sh +npm install +``` + +This will install dependencies for both the Mobile App and the backend GraphQL API, Prose. + +### Install the Expo CLI + +[Expo](https://expo.io/) is the phenomenal toolchain that Lexicon uses to develop and build the Mobile App. + +We will later use the Expo CLI to launch the Mobile App - either on your device or in a simulator. + +You can install the Expo CLI with the following command: + +```sh +npm install --global expo-cli +``` + +Further information is available in the [Expo docs](https://docs.expo.io/). + +Then, verify that Expo is available in your `PATH` with the following: + +```sh +$ expo --version + +``` + +### Install the EAS CLI + +[Expo Application Services (EAS)](https://expo.dev/eas/) is an integrated set of cloud services for Expo and React Native apps. + +We will use the EAS CLI to build and publish the Mobile App. + +You can install the EAS CLI with the following command: + +```sh +npm install --global eas-cli +``` + +Further information is available in the [Expo docs](https://docs.expo.dev/eas/). + +Then, verify that EAS is available in your `PATH` with the following: + +```sh +$ eas --version +eas-cli/ +``` + +### Ready to Go! + +That's all we need for this step. + +Next, there is an optional guide to help you if you're not too familiar with setting up a server on a cloud provider. + +You're free to skip this if you're already adept at this process. + +After that, we'll look into how we can prepare Discourse to connect with the Lexicon Mobile App. + +If you don't already have a Discourse server setup, we'll get into that as well. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/updating.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/updating.md new file mode 100644 index 00000000..46fcfdd1 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/updating.md @@ -0,0 +1,68 @@ +--- +title: Update your App +--- + +## EAS Update + +EAS Update is the successor to `expo publish`. This service helps to update projects using the `expo-updates` library. + +In particular, it enables you to push quick fixes to your users in between full-fledged app store submissions. + +With EAS Update, there is no need to recompile the app with its non-native parts, such as TypeScript code, styling, or image assets. [Click here](https://docs.expo.dev/eas-update/introduction/) to learn more about EAS Update. +:::note +You are required to build the app with [EAS Build](building) before using the EAS Update. +::: + +### Configuration + +Let's get started by configuring EAS update. Feel free to check out the [complete guide](https://docs.expo.dev/build-reference/build-configuration/) from Expo for further details. + +```bash +eas update:configure +``` + +Running this command will add `expo.updates.url` and `runtimeVersion.policy` in `app.json`. + +:::caution + +As mentioned in the [Expo documentation](https://docs.expo.dev/build/updates/#previewing-updates-in-development-builds), you can no longer launch your app in Expo Go (using `expo start`) after adding the `runtimeVersion` field in `app.json`. It is recommended to use `expo-dev-client` instead to create a development build. + +```bash +eas -p all -e development +``` + +or if you still wish to use Expo Go, please remove `runtimeVersion` field from `app.json` before running `expo start`. +::: + +### Updating + +After making the necessary changes, you can push updates using this command: + +```bash +eas update –-branch –-message “” +``` + +The branch name here is the same as the build profile name when building the app. +For example, if you had previously built the app with this command: + +```bash +eas build –p all –e preview +``` + +Then you can later update it using: + +```bash +eas update –-branch preview –-message “Fixing typos” +``` + +Once the update is complete, force close and reopen the installed app twice to view the update. + +## All Done! 🙌 + +That's it for the tutorial. Great work. + +We hope that this has served as an informative guide to help familiarize you with Lexicon and how you can make use of it. + +If you haven't already, check out the [Lexicon Documentation](../) to get a deeper understanding of the project and how it all works. + +If you have any questions, comments, feedback, or want to contribute, please reach out to us on Github! diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/white-label.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/white-label.md new file mode 100644 index 00000000..f0192667 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/tutorial/white-label.md @@ -0,0 +1,82 @@ +--- +title: White Label your App +--- + +## Customize the Splash Screen and App Icon + +In order to customize the app for your own brand, you will likely want to provide your own assets for the **Splash Screen** and the **App Icon**. + +The **Splash Screen** - sometimes also referred to as the Launch Screen - is what appears while the app is launching. Some apps also display this to help conceal private information when the app is put into background mode. + +The **App Icon** is what is used to represent the app on the user's device, such as on the home screen and when listing it in the device's settings. + +Both of these assets often contain your logo in one form or another. For example, the App Icon for the Gmail app is the multi-colored outline of an envelope. Then, when launching the Gmail app, you will notice that the Splash Screen includes a larger version of the App Icon. + +### Customizing the Splash Screen + +:::info +Expo does not currently support dark mode for splash screens. +::: + +The assets used for the splash screen in the Mobile App are located at `frontend/assets/images/splash.png` and `frontend/assets/images/splashDark.png`. + +Above, we mention splash screen assets for both Dark Mode and Light Mode. + +However, unfortunately at this time, Expo does not support Dark Mode for Splash Screens. We have only included both so that they're ready when Expo finally does support this. + +In the meantime, you're free to adjust `splash.png` to influce what asset appears. + +In order to change it, you can simply replace the existing file with your own `splash.png`. + +To find out more about the Splash Screen image size and other details, please see the [Expo Splash Screen Guide](https://docs.expo.io/guides/splash-screens/). + +#### Futher Configuration + +To resize the Splash Screen image and change its background color, first open `frontend/app.json` and locate the `"splash"` field within it. + +As illustrated by the excerpt below, there are multiple fields that can be used to further adjust the Splash Screen: + +```json +"splash": { + "image": "./assets/splash.png", + "resizeMode": "contain", + "backgroundColor": "#FFFFFF" +}, +``` + +**image** + +The `image` field is fairly self-explanatory - it allows you to adjust what path will be used to locate the Splash Screen image. + +**resizeMode** + +The `resizeMode` field allows you to manage how the Splash Screen image will be resized to maintain its aspect ratio: + +- `contain` - Resize the image to make sure the whole image is visible. This is the default setting. +- `cover` - Resize the image to cover the entire container (in this case the whole screen) by either stretching or cropping the image as needed. + +Further details of how `contain` and `cover` behave are covered in the previously mentioned [Expo Splash Screen guide](https://docs.expo.io/guides/splash-screens/). For an even more detailed explanation, you can read [this post](http://blog.vjeux.com/2013/image/css-container-and-cover.html). + +**backgroundColor** + +The `backgroundColor` field enables you to specify the color of the background behind the Splash Screen image. Removing this value will result in usage of the default value, which is a white background color. + +### Customizing the App Icon + +Customizing the App Icon in Lexicon is nearly the same process as customizing the Splash Screen. + +The image asset for the Mobile App's icon is located at `frontend/assets/icon.png`. To customize it, simply overwrite that file with your own `icon.png`. + +## Further Customization + +We get into more detail about how to white label your app in the [White Labeling](../white-labeling) section of the documentation. + +In particular, this includes customizing and extending the theme's color palette, icons, and even fonts. + +Should you wish to customize anything not covered in that section, get in touch with us, and we'll see how we can help you make it a reality. + +## Awesome Work + +Your app looks cool now 😎. However, it's only accessible to you. + +Next, we'll cover how you can actually [build your app](building), so you can share it with the world. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/white-labeling.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/white-labeling.md new file mode 100644 index 00000000..be413831 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-1.0.0/white-labeling.md @@ -0,0 +1,13 @@ +--- +title: Overview +--- + +The Lexicon Mobile App allows you to customize its appearance through a process known as **White Labeling**. + +If you're unfamiliar with this term, it's essentially the process of branding an existing application specifically for your users. + +White Labeling allows you to configure the app with your own logo, app icon, color theme, fonts, and so on. + +The idea is that your users won't know that the Lexicon team built this app. Its appearance will be completely customized to your brand. + +To learn more about White Labeling the Lexicon Mobile App, continue to the next section. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0.json b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0.json new file mode 100644 index 00000000..e0757540 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0.json @@ -0,0 +1,50 @@ +{ + "version.label": { + "message": "2.0.0", + "description": "The label for version 2.0.0" + }, + "sidebar.docs.category.Lexicon": { + "message": "Lexicon", + "description": "The label for category Lexicon in sidebar docs" + }, + "sidebar.docs.category.Getting Started": { + "message": "入门", + "description": "The label for category Getting Started in sidebar docs" + }, + "sidebar.docs.category.Configuring the Mobile App": { + "message": "配置移动应用", + "description": "The label for category Configuring the Mobile App in sidebar docs" + }, + "sidebar.docs.category.White Labeling": { + "message": "自定义白标", + "description": "The label for category White Labeling in sidebar docs" + }, + "sidebar.docs.category.Deploying Prose": { + "message": "部署 Prose", + "description": "The label for category Deploying Prose in sidebar docs" + }, + "sidebar.docs.category.Configuring Discourse": { + "message": "配置 Discourse", + "description": "The label for category Configuring Discourse in sidebar docs" + }, + "sidebar.docs.category.Discourse Plugin": { + "message": "Discourse 插件", + "description": "The label for category Discourse Plugin in sidebar docs" + }, + "sidebar.docs.category.Push Notifications": { + "message": "通知推送", + "description": "The label for category Push Notifications in sidebar docs" + }, + "sidebar.docs.category.Email Deep Linking": { + "message": "邮件深度链接", + "description": "The label for category Email Deep Linking in sidebar docs" + }, + "sidebar.docs.category.Publishing your App": { + "message": "发布您的 App", + "description": "The label for category Publishing your App in sidebar docs" + }, + "sidebar.tutorial.category.Tutorial": { + "message": "教程", + "description": "The label for category Tutorial in sidebar tutorial" + } +} diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/app-store.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/app-store.md new file mode 100644 index 00000000..0e2d1b24 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/app-store.md @@ -0,0 +1,278 @@ +--- +title: 发布到 iOS 应用商店 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +现在你应该已经对 Lexicon 移动应用做了一些小的调整，并准备好发布，以便用户可以下载。 + +在这个页面中，我们将介绍在 iOS 上发布的过程。 + +## 前提 {#prerequisites} + +- 拥有 Apple 开发者账户 +- 拥有 Expo 账户 +- 在开发机器上安装了 XCode +- EAS CLI 2.6.0 或更新版本 +- [Lexicon Discourse 插件](./discourse-plugin.md)已经安装在你的 Discourse 站点上 + +要开始使用 TestFlight 并发布你的应用，你需要一个 **Apple 开发者账户**。 + +这将使你能够在提交到 TestFlight 和最终 App Store 的过程中与 Apple 互动。 + +你还需要一个 [Expo 账户](https://expo.dev/signup)，这样你就可以构建你的应用、下载它并上传到 Apple 的服务器。 + +最后，你需要已经下载并安装了 [Xcode](https://developer.apple.com/xcode/)，这是你用来上传构建好的应用到 Apple 服务器的工具。 + +:::note +如果你还没有 Apple 账户，你需要先加入 [Apple 开发者计划](https://developer.apple.com/programs/enroll/)。请注意，这是需要年费的。 + +除此之外，你还需要确保你已经注册了一个 [Expo 账户](https://expo.dev/signup)，这样你就可以使用 [EAS Submit](https://docs.expo.dev/submit/introduction/) 等功能。 +::: + +## 注册一个新的 Bundle ID {#register-a-new-bundle-id} + +Apple 的 App Store 中的每个应用都有一个唯一的 **Bundle Identifier**，或 Bundle ID。 + +为了在任何地方发布应用，包括 TestFlight，你都需要为你的应用注册一个 Bundle ID。 + +通常，ID是 `com..` 的格式。 + +比如说，如果你的公司名字是 Expo，你的应用名字是 Expo Go，那么你的 Bundle ID 可以是： + +``` +com.expo.expogo +``` + +你可以按照以下步骤获取一个 Bundle ID。 + +- 前往 [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/bundleId/add/bundle)。 +- 填写以下字段，然后点击 `Continue`。 + Regsiter App + + - **Description**: 你可以将应用名字作为描述。 + - **Bundle ID**: 选择 `Explicit`，然后在输入框中插入你的 Bundle ID。 + - Capabilities： 可以不填写此字段。 + +## 在 App Store Connect 中添加一个新的应用 {#add-a-new-app-in-app-store-connect} + +步骤： + +- 登录你的 [App Store Connect](https://appstoreconnect.apple.com/) 账户。 +- 点击 `My Apps`。 + App Connect +- 点击 `+` 按钮添加新的应用。 +- 填写关于你的应用的信息，然后点击 `Create`。 + Add New App + + - **Platforms**: 选择 `iOS`。 + - **Name**: 应用的名字，将会出现在 App Store 和用户的设备上。 + - **Primary Language**: 如果本地化的应用信息不可用，将使用的主要语言。 + - **Bundle ID**: 选择你在上面创建的 Bundle ID。 + - **注意**：一定要确认它是正确的，因为之后无法更改。 + - **SKU (Stock Keeping Unit)**: 用于区分你的应用和其他应用的唯一 ID，类似于产品 ID。 + - **User Access**: 完全访问意味着所有用户都可以访问应用，而有限访问意味着只有在 App Store Connect 中定义的某些角色才能访问应用。 + +## 配置 {#configuration} + +在 App Store Connect 中创建应用之后，你需要回到代码库中进行一些调整。 + +### 构建配置 {#build-config} + +:::note +如果你还没有安装 EAS CLI，请按照 [教程](tutorial/setup#install-the-eas-cli) 中的说明进行安装。 +::: + +首先，你需要确保在 `frontend/app.json` 中设置了你的应用名字和 slug。[slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) 用作 Expo Web 服务上应用的 URL 的一部分，建议使用 kebab-case（例如，`my-lexicon-app`）。 + +将这些占位符替换为你想要的值： + +:::info +请注意，下面的样例也包含了 `scheme`。如果你想在你的应用中支持 [电子邮件深度链接](./email-deep-linking/intro.md)，**你必须指定一个 scheme**，然后使用相同的 scheme 配置 Lexicon Discourse 插件。 +::: + +```json +"name": "", +"slug": "", +"scheme": "", +``` + +接下来，在 `frontend/` 目录运行以下命令来配置 EAS Build： + +```bash +eas build:configure +``` + +EAS CLI 会提示你指定 `android.package` 和 `ios.bundleIdentifier`，如果这些值在 `app.json` 中尚未提供的话。你需要将你刚刚在 App Store Connect 中注册的 Bundle ID 作为 `bundleIdentifier`。 + +然后你可以看到 `frontend/app.json` 文件的 `ios` 部分的值已经更新。 + +```json + "ios": { + "supportsTablet": false, + "buildNumber": "1.0.0", + "bundleIdentifier": "", + "config": { + "usesNonExemptEncryption" : false + } + }, +``` + +:::note +此处将 `usesNonExemptEncryption` 设置为 `false`，是因为 Lexicon 不提供该功能。 + +更多详细信息，请查看[这个链接](https://developer.apple.com/documentation/bundleresources/information_property_list/itsappusesnonexemptencryption)。 +::: + +### 配置 Config 值 {#setup-config-values} + +:::info +当你发布应用时，需要将 Prose 部署到一个可公开访问的地方，比如 AWS 或 DigitalOcean 这样的云托管服务商。如果 Prose 只在你的本地机器上运行，那么下载你的应用的用户将无法使用它。 + +如果你还没有部署 Prose，请查看[此文档](deployment)。 +::: + +接下来，在 `Config.ts` 中为你的构建配置 **Prose URL**。你可以为每个构建通道设置不同的 URL。 + +:::note +在 Lexicon 的原始版本中，**Prose URL** 是在 `frontend/.env` 中指定的。不过，作为迁移到 Expo 的 EAS 功能的一部分，我们将配置集中到了 `frontend/Config.ts` 中，以免你需要在多个地方维护它，正如[Expo 文档](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update)中所建议的那样。 +::: + +```ts +const config = { + // ... + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, +}; +``` + +### 配置 Apple 开发者账户 {#setup-apple-dveloper-account} + +最后，请在 `eas.json` 中使用你的账户信息调整这些字段，以便提交应用： + +```json + "base": { + "ios": { + "appleId": "", + "ascAppId": "", + "appleTeamId": "" + }, + ... + }, +``` + +- **appleId**: 你的 apple ID (e.g., `john@gmail.com`). +- **ascAppId**: 你的 App Store Connect app ID. 跟着这份[教程](https://github.com/expo/fyi/blob/main/asc-app-id.md)可以找到你的 ascAppID (e.g., `1234567890`). +- **appleTeamId**: 你可以在[这里](https://developer.apple.com/account/) (e.g., `12LE34XI45`)查看你的 apple team ID. + +## 构建iOS应用 {#build-your-app-for-ios} + +在发布之前，你需要指示 Expo 生成一个 iOS 构建。 + +在发布之前，建议使用 `preview` 配置文件构建你的应用，以验证它是否按预期工作。查看[这个教程](tutorial/building)了解更多关于构建配置文件的信息。 + +运行以下命令： + +```bash +eas build --platform ios --profile preview +``` + +当你运行上面的命令时，Expo 会提示你输入你的 Apple ID 和密码。 + +上述步骤完成后，请登录到你的 [Expo](https://expo.dev) 账户并下载你新构建的应用。 + +在[Expo web 控制台](https://expo.dev)中找到你的项目，然后点击位于屏幕左侧的 **Builds** 菜单。 + +- 点击你想安装的项目 + Builds + +- 点击 `Build Artifact` 一栏中的 `Download` 按钮下载 iOS 构建。 + Build Artifact + +随后将下载一个包含你的应用的 tar 文件。解压文件，然后将其拖到模拟器中安装。查看[教程](tutorial/building#1-preview)中的这一部分了解如何在真实设备上运行应用。 + +验证应用按预期运行后，你就可以继续构建发布版本： + +```bash +eas build --platform ios --profile production +``` + +生产构建的方法与生成预览构建的方法类似。但与预览构建不同的是，你无法在 iOS 模拟器中启动生产构建，它仅用于发布到 App Store。 + +构建完成后，你可以继续将其提交给 Apple。这个过程通常涉及到 Apple 的 TestFlight 服务。 + +## 提交到 TestFlight {#submit-to-testflight} + +TestFlight 是 Apple 开发者计划的一个关键组成部分，它允许开发者在较少的审核要求下向测试用户提供应用。 + +通过 TestFlight，你可以邀请用户测试你的应用，并在发布到 App Store 之前收集他们的反馈。你可以在[这里](https://developer.apple.com/testflight/)了解更多关于 TestFlight 的信息。 + +使用 EAS Submit 提交 iOS 应用要容易得多。这在[教程](tutorial/publishing)中有更详细的介绍。 + +运行以下命令开始将应用发布到 TestFlight： + +```bash +eas submit --platform ios --profile production +``` + +这个过程可能需要一些时间，因为 Apple 会对你的应用进行审核。审核成功后，我们就可以在 App Store Connect 中检查构建。 + +在 App Store Connect 中，点击 TestFlight 选项卡。 + +你会看到你构建版本的[状态](https://help.apple.com/app-store-connect/#/dev3d6869aff)。 + +- **红色**表示你需要执行一些操作。 +- **黄色**表示流程的某些方面是待定的，你或者 Apple 的某些操作尚未完成。 +- **绿色**表示构建正在 TestFlight 中测试，或者已经准备好提交审核。 + +在 Apple 官方测试人员验证你的应用之前，你无法开始使用 TestFlight 进行测试。 + +为了让 Apple 能够正确测试你的 Lexicon 应用，他们需要登录你的 Discourse 站点的凭证。 + +所以在提交你的应用之前，你需要在 Discourse 中创建这些凭证，并在 App Store Connect 中指定它们。 + +- 在 App Store Connect 中，点击你的应用。 +- 点击 TestFlight 应用。 +- 在左侧边栏中点击 Test Information。 +- 填写必填字段，然后勾选 `Sign in required` 复选框，并输入凭证。 + Review Information Sign In +- 请提供一个联系人的信息，以便审核团队在需要时联系。 + Review Information Contact + +### 指定 Beta 测试用户 {#specify-users-for-beta-testing} + +Beta 测试用户可以属于内部组或外部组。 + +你可以通过转到内部组部分，然后点击 **App Store Connect Users** 来指定内部用户。 + +类似地，你可以通过选择外部组，然后点击 **Add External Testers** 来指定外部用户。 + +#### 更多信息 {#more-information} + +TestFlight 和 App Store Connect 是一些复杂的工具，可以帮助你提交、测试和发布你的应用。 + +如果你有进一步的问题或者只是想了解更多，我们建议你使用 Apple 的文档，这些文档质量很高。 + +有关 TestFlight 的更多信息，请阅读[文档](https://developer.apple.com/testflight/)。 + +同样，关于使用 TestFlight 进行 Beta 测试的具体信息，请查看[Testing Apps with TestFlight](https://testflight.apple.com/)。 + +## 发布到 App Store {#publish-to-the-app-store} + +一旦你成功通过了 Apple 的审核流程，并且从你的 Beta 测试人员那里收到了足够的反馈，你就可以发布到 App Store 并上线了！:tada: + +此外请再次确认如下事项： + +- 你的 Discourse 实例在线、可访问，并且正常运行。 +- 构建版的应用已经配置为指向正确的 Prose 服务器。 +- 你的 Prose 服务器在线、可访问并且正常运行。 +- 你的 Prose 服务器已经按照[生产环境的推荐指南](dedicated#configure--deploy-prose)进行了部署。 + - 特别是，确保其流量是通过 SSL 证书加密的。 + +接下来，我们将指导你完成在 Google Play Store 上发布 Android 设备的应用的过程。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/assets.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/assets.md new file mode 100644 index 00000000..23a01102 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/assets.md @@ -0,0 +1,47 @@ +--- +title: 应用图标和其他资产 +--- + +Lexicon 移动应用程序包含很多资产，可以替换以进行白标。 + +可以修改的资产如下： + +## 应用 Logo {#app-logo} + +用于在应用程序中显示应用 Logo，例如在登录、注册和 2FA 场景中。 + +这些资产位于 `frontend/assets/images/logo.png` 和 `frontend/assets/images/logoDark.png`。`logo.png` 用于浅色主题，`logoDark.png` 用于深色主题。要自定义它，只需用您自己的 `logo.png` 和 `logoDark.png` 替换现有文件。 + +## Favicon {#favicon} + +用于显示应用程序 Logo。 + +这些资产位于 `frontend/assets/favicon.png`。要自定义它，只需用您自己的 `favicon.png` 替换现有文件。 + +## 占位图像 {#image-placeholder} + +用于在加载图像时暂时占据图像位置。 + +这些资产位于 `frontend/assets/images/imagePlaceholder.png`。要自定义它，只需用您自己的 `imagePlaceholder.png` 替换现有文件。 + +## 图标 {#icons} + +用于在应用程序内显示图标。 + +这些资产位于 `frontend/assets/icons` 文件夹。如果您想添加更多图标或编辑剩余图标，需要将图标插入到 `frontend/assets/icons/` 文件夹，并在 `frontend/src/icons.ts` 中导入它们。 + +图标有一些标准，例如： + +### 保持视觉一致性的统一图标尺寸 {#uniform-icon-size-to-maintain-visual-consistency} + +UI 是围绕图标的默认基本尺寸 28x28px 设计的。 + +如果您调整此尺寸，您可能需要修改主题或字体的其他方面，以保持简洁的外观。 + +同样，如果您提供一个不符合这些尺寸的新图标，可能会遇到视觉效果不一致的问题。 + +### SVG 图标通过 `currentColor` 控制其填充颜色 {#svg-icons-have-their-fill-color-controlled-via-currentcolor} + +如果您要添加一个新图标，希望它与主题的颜色交互，请确保其颜色未硬编码，并且设置为 `currentColor`。 + +如果您对这个概念不熟悉，请查看 [MDN 规范中的 SVG 颜色值](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/color)。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/commercial-support.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/commercial-support.md new file mode 100644 index 00000000..93a34d99 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/commercial-support.md @@ -0,0 +1,9 @@ +--- +title: 商业支持 +--- + +通过官方支持，您可以直接从核心团队获得专家帮助。我们提供应用程序定制、专属支持、优先处理功能请求、部署策略、最佳实践建议、设计决策和团队增补。 + +此外，我们还欢迎非技术身份的站长进行咨询，以定制、部署和启动适用于其 Discourse 用户的移动端应用。 + +请通过 support@kodefox.com 与我们联系以获取咨询服务。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/concepts.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/concepts.md new file mode 100644 index 00000000..c316f4ef --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/concepts.md @@ -0,0 +1,68 @@ +--- +title: 概念和架构 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Prose: Discourse 的 GraphQL 接口： {#prose-discourse-through-graphql} + +值得一提的是，Discourse已经为开发者提供了一个传统的RESTful API。 + +但是[官方文档](https://docs.discourse.org/)指出，这个 API 仅仅作为开发的落脚点使用，尚不完整。 + +> 注意：对于未列出的任何 API 入口，您可以按照 Discourse API 逆向工程指南来找出如何使用它 。 +> +> ——**Discourse API 文档** + +Discourse 核心团队以及[社区](https://meta.discourse.org)的成员经常通过[鼓励开发者逆向工程API](https://meta.discourse.org/t/how-to-reverse-engineer-the-discourse-api/20576)来解答有关API的问题。截至本文撰写时，关于如何对 API 逆向工程的主题已经链接到了支持论坛上的近200个其他主题。 + +为了帮助您简化这个过程，Prose努力规范了API的一个子集，希冀在您开发 Discourse 时可以节省一些时间。 + +### GraphiQL {#graphiql} + +Prose 的 GraphQL 实现包括一个[浏览器内的GraphQL IDE](https://www.graphql-yoga.com/docs/features/graphiql)，称为[GraphiQL](https://github.com/graphql/graphiql)，它允许开发者轻松地参考整个文档和模式，并对正在运行的Discourse实例进行查询。 + + + +这意味着您可以快速了解一个方法的行为方式以及它需要哪些参数，而无需查阅支持帖子或逆向 REST API。 + +### 为什么选择GraphiQL？ {#why-graphiql} + +关于 GraphQL 的[优势](https://www.howtographql.com/basics/1-graphql-is-the-better-rest)和[权衡](https://lwhorton.github.io/2019/08/24/graphql-tradeoffs.html)的文章不胜枚举。 + +我们很清楚，GraphQL 并不是解决其他 API 范例所有问题的神奇解决方案。 + +尽管如此，我们选择使用 GraphQL 构建 Lexicon 有两个主要原因。 + +1. 我们的团队熟悉并精通 GraphQL，并且非常喜欢使用它。 + +2. 工具、库和自动生成的文档提供了开箱即用的特性，我们可以毫不费力地将这些特性传递给其他人。 + +## 为什么选择 Expo？ {#why-expo} + +[Expo](https://docs.expo.io/)既是一个框架，也是一个用于构建通用 React 应用程序的平台。特别是，在使用 React Native 构建移动应用程序时，它提供了卓越的开发体验。 + +我们发现，Expo 使我们作为开发者更加高效，并且还提供了出色的服务，以便简化构建和发布 React Native 应用程序的整个过程。 + +特别是，使用[Lexicon Discourse Plugin](./discourse-plugin.md)的 Discourse 站点可以通过 Expo 的[推送通知服务](https://docs.expo.dev/push-notifications/overview/)获得[推送通知](./push-notifications)，该服务将 Google 和 Apple 的推送服务抽象为一个简单的接口。 + +## Lexicon 架构 {#lexicon-architecture} + +Lexicon Stack 相当简单，只包含3个主要部分： + +- Lexicon 移动应用程序 +- Prose GraphQL API +- 运行中的、可访问的Discourse实例 + - 可选地，您可以安装我们的[Discourse Plugin](./discourse-plugin.md)以启用其他功能。 + +下面是一个说明Lexicon移动应用程序的典型架构的图示。 + +IOS Lexicon 登录页面 + +如上所示，移动应用程序向部署的 Prose GraphQL 服务器发出请求。 + +Prose 服务器已配置为指向开发者选择的可用 Discourse 实例。 + +如果安装了[Lexicon Discourse Plugin](./discourse-plugin.md)，将会暴露额外的接口，Prose已经知道如何与之通信。 + +然后，数据从 Discourse 流经 Prose，并通过 GraphQL 接口返回到移动应用程序。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/contributing.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/contributing.md new file mode 100644 index 00000000..83e38480 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/contributing.md @@ -0,0 +1,131 @@ +--- +title: 提交贡献 +--- + +感谢您对提交贡献的兴趣! :sparkles: + +我们十分感谢您为推动 Lexicon 进步而付出时间和精力。 + +这有一些指导可以帮助您更好地了解如何为 Lexicon 提交贡献。 + +## 反馈异常 {#reporting-bugs} + +反馈给我们异常的最佳方式是在 [Github](https://github.com/lexiconhq/lexicon) [创建一个新的 issue] (https://github.com/lexiconhq/lexicon/issues/new)。 + +同时我们强烈建议在创建新 issue 之前搜索现有的开放或已经关闭的 issue。 + +在你创建 issue 时，请确保包含以下内容： + +- 异常的详细描述及其表现 + +- 你期望的表现 + +- 复现异常的步骤 + +- 你观察到异常的设备和版本的详细信息 + +- 截图或屏幕录像，虽然不是必须的，但非常推荐 + +一旦我们收到您的异常报告，将对其进行分类并进行相应的标记。 + +## 向项目提交贡献 {#contribute-to-the-project} + +想名列我们的贡献者列表 :clap:? + +我们很乐意接收您提交的 PR，无论是解决现有问题、添加新功能，还是改进文档。 + +要开始贡献，请按照以下说明操作。 + +### 操作步骤 {#instructions} + +**1. Fork [官方 Lexicon 仓库](https://github.com/lexiconhq/lexicon)** + +您可能已经知道这个步骤 - 点击仓库右上角的 **Fork** 按钮。 + +**2. 克隆 Lexicon 的 Fork** + +请确保将 **_您的_** fork 克隆到您的开发环境中（而不是克隆主 Lexicon 仓库）。 + +``` +$ git clone https://github.com/YOUR_USERNAME/lexicon.git +``` + +如果您需要进一步指导，请查看我们的 [快速入门](quick-start#installation) 部分。 + +请注意，快速入门部分指导您克隆 Lexicon 仓库。因此，请确保将上述 URL 中的 `YOUR_USERNAME` 更改为您的用户名。 + +**3. 运行并连接应用程序至 Prose 和 Discourse 主机** + +在这一步中，您需要确保 Lexicon 移动应用程序连接到您的 Prose 服务器和 Discourse 主机，参照 [**配置**](setup#discourse-host) 部分的说明。 + +如果您已经部署了一个指向 Discourse 站点的 Prose 服务，您只需配置 Lexicon 移动应用程序指向您的 Prose 部署地址即可。 + +但是，如果您没有已部署的 Prose，或者您打算对 Prose 服务器本身进行调整，您需要确保 Lexicon 移动应用配置为指向您本地运行的 Prose 服务器。 + +**4. 开始贡献** + +到这一步，您应该已经准备好开始主要工作了，比如功能开发、修复 bug 或其他贡献。 + +请记住，您的 IDE 中需要安装 [**ESLint**](https://eslint.org/docs/user-guide/getting-started) 和 [**Prettier**](https://prettier.io/) 插件，因为这些是 Pull Request 检查所必需的。 + +我们建议使用 [VSCode](https://code.visualstudio.com/) 进行开发，因为这是我们用来开发 Lexicon 的 IDE。但是，这取决于您，只需确保您的 IDE 中的 ESLint 和 Prettier 正常运行即可。 + +**5. 运行测试套件** + +请按照 [**步骤**](setup#run-the-test-suite) 运行 Lexicon 测试套件。 + +为了缩短反馈周期，建议您确保所有测试在本地都通过后再推送，尤其是如果您已经有一个开放的 PR。 + +这主要是因为我们已经配置了 Github 项目，如果任何构建步骤失败，将阻止 PR 合并。 + +如果审核发现测试失败，他们将无法快速审核，很可能会要求您在再次请求审核之前解决构建本身的问题。 + +**6. 暂存、提交并推送本地更改** + +如果你对这些操作并不熟悉，请查看 Github 的这篇[优秀文章](https://github.com/git-guides/#learning--mastering-git-commands)学习操作。 + +**7. 创建新的 Pull Request** + +你的代码已经准备好提交了！ :tada: + +前往 Lexicon 的 [Pull Requests 选项卡](https://github.com/lexiconhq/lexicon/pulls)， 然后比较你的分支和主分支之间的更改。 + +再次检查并确保你没有推送任何不想包含在 PR 中的内容。 + +然后，从你 fork 的仓库中创建一个新的 Pull Request。 + +请确保遵循 Pull Request 模板，添加相关标签，并请提及你正在解决的问题，以帮助我们跟踪正在进行的工作。 + +## 和我们分享你的见解 {#share-your-thoughts-with-us} + +我们非常感谢您的反馈和建议。如果您有任何新的想法，我们很乐意在 [Issues 标签页](https://github.com/lexiconhq/lexicon/issues)看到您的想法。 + +## 分享给更多人 {#spread-the-word} + +如果您在社交媒体上分享您使用 Lexicon 的精彩体验，请告诉其他人，并在 Twitter 上标记我们 [@GetLexicon](https://twitter.com/GetLexicon)。 + +如果您使用 Lexicon 构建了应用程序，请告诉我们。我们很乐意帮助您分享您所构建的内容！ + +## 改进文档 {#improve-the-documentation} + +最后，如果您发现 Lexicon 文档中有任何问题，或者认为您可以做得更好，您可以按照以下简要说明开始。 + +在项目的根目录下，运行以下命令可以在本地生成并查看文档： + +```sh +npm run docs:start +``` + +类似地，您可以使用以下命令仅构建文档： + +```sh +npm run docs:build +``` + +所有文档都在 `documentation/` 目录下，用于生成本站的 Markdown 页面位于 `documentation/docs` 下。 + +如果您最终提交了 PR 来改进文档，请确保为您的 PR 添加 `Documentation` 标签。 + +:::note +如果你还有其他问题，快来问我们。我们很高兴能提供些帮助。 :smile: +::: diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/customize.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/customize.md new file mode 100644 index 00000000..9a4c8ba2 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/customize.md @@ -0,0 +1,28 @@ +--- +title: 个性化 +--- + +## 主题 {#theming} + +作为[白标支持](white-labeling) 的一部分，Lexicon 允许您根据自己的颜色方案自定义移动应用的主题。 +您可以根据自己的选择配置基本的系统颜色。 +您还可以自定义图标、字体，甚至移动应用内部的错误消息。 +要开始使用，请查看[白标](white-labeling)部分下的[主题](theming)页面。 + +## 自定义移动应用资产 {#white-labeling-the-mobile-app-assets} + +为了为您的用户提供与您的品牌相匹配的独特体验，您可以在他们的设备上自定义启动页和应用图标。 + +这可以将所有 Lexicon 品牌替换为您自己的品牌。 + +有关详细信息，请查看本文档的[Tutorial](tutorial/white-label)和[白标](white-labeling)部分。 + +## 启用额外的 Discourse 功能 {#enabling-additional-discourse-features} + +如您可能已经知道的，Discourse 是一款高度可定制的软件。您可以在 Discourse 实例的管理站点设置页面上定制许多内容。 + +Lexicon 会尽力将这些设置转换为 Lexicon 移动应用中的设置，例如`授权扩展`。 + +一般来说，我们已经尽力让 Lexicon 直接使用 Discourse 作为 Lexicon 应用内展示和执行的信息源。 + +如果您发现 Lexicon 存在任何应该响应但却没有响应的设置，请通过 issue 告诉我们。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/dedicated.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/dedicated.md new file mode 100644 index 00000000..3eb862a4 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/dedicated.md @@ -0,0 +1,301 @@ +--- +title: 配置与部署 +--- + +正如[概览](deployment)中所提到的，本节旨在指导您配置和部署 Prose 到专用实例。 + +## 决定在哪里托管 {#decide-on-where-to-host} + +首先，您需要回答以下问题。您想在哪里托管 Prose？ + +虽然有许多选项，这些选项因项目和开发人员的偏好而异，但通常最简单的方法是使用您选择的云服务商。 + +在[Lexicon 教程](tutorial/setup-cloud-server)中，我们通过使用 Digital Ocean 演示了这个过程。 + +如果您对此步骤感到困惑，或者没有偏好，您应该花些时间来解决这个问题。 + +但是，如果您已经知道自己在做什么，请随意使用您选择的任何云服务商或其他托管方案。 + +### 托管条件清单 {#hosting-checklist} + +一旦您决定了托管方案，通过下面的清单验证一切是否按预期设置。 + +#### ✅ 确保主机上的访问和权限 {#-ensure-access--permissions-on-the-host} + +您需要至少能够登录到主机。一些云服务商提供虚拟的基于 Web 的终端，但理想情况下，您可以直接获取登录凭据。 + +如果您的主机位于基于 UNIX 的环境中，您还应该具有以 `sudo` 运行命令的权限。 + +快速检查的方法是尝试使用 `sudo` 运行命令： + +```sh +$ sudo ls +``` + +不过，如果您的主机环境受到限制，您只需要一种方法将 Lexicon 源放到主机上，安装其依赖项，并在端口上公开它。 + +请记住，受限制的托管环境并不理想，特别是因为配置教程中使用了 Docker。 + +#### ✅ 确保主机以您需要的方式可访问 {#-ensure-the-host-is-reachable-in-the-way-you-need-it} + +通常，这意味着您的主机可以在公网上访问。 + +然而，您可能有不同的约束条件，例如只需要主机从 VPN 或本地网络中访问。 + +
+ +一旦您配置好了一个主机，可以按您需要的方式访问它，您就可以开始在其上配置 Prose。 + + +## 配置与部署 Prose {#configure--deploy-prose} + +### 不使用 Docker {#without-docker} + +通常不使用 Docker 部署 Prose 意味着更多的手动步骤，可能会因平台而异。 + +我们已经在教程中很好地涵盖了这种方法。特别是，您可以在[设置 Prose GraphQL API](tutorial/install-prose#install-manually)页面上深入了解。 + +### 使用 Docker {#with-docker} + +Prose Docker 镜像预先配置为使用 **[PM2](https://pm2.keymetrics.io/)** 运行 Prose，PM2 是一个用于在生产环境中运行 Node 进程的复杂工具集。 + +这通常是一个合理的设置，甚至可以直接将 PM2 服务器暴露给主机上的请求。 + +但是，如果您更喜欢不同的设置，也许使用 Nginx 作为 Docker 容器的反向代理，可以随意修改 Dockerfile 以满足您的需求。 + +#### 安装 Docker {#install-docker} + +**[Docker](https://www.docker.com/)** 是一个容器化框架，它使构建、管理和部署应用变得更加安全、可靠和可重现。 + +有很多关于在给定操作系统上安装 Docker 的指南。 + +Ubuntu 是大多数云提供商提供的操作系统之一。 + +Docker 为此提供了一个[完整教程](https://docs.docker.com/engine/install/ubuntu/)，甚至提供了一个方便的脚本，您可以在两行中运行： + +```sh +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh +``` + +无论您选择何种方式，只需确保 Docker 在主机上运行后再继续。 + +#### 配置环境变量 {#configure-environment-variables} + +完整的 Prose 环境变量列表可以在[环境变量](env-prose)页面上找到。 + +简而言之，至少您需要确保 `PROSE_DISCOURSE_HOST` 已设置。 + +另一个需要注意的变量是 `PROSE_APP_PORT`。默认为 80 端口，这会让 Prose 在该端口上监听。 + +根据您的设置，您可能希望它监听不同的端口。 + +
+ +#### 从 Dockerfile 构建 Prose {#build-prose-from-the-dockerfile} + +如果您想使用 Docker 手动构建 Prose，请从 **项目根目录** 运行以下命令。 + +如果您想对 Dockerfile 进行一些调整，这可能对您有所帮助。 + +否则，如果您只想从 Docker Hub 拉取最新的 Prose 构建，您可以[跳到下一步](#pulling-the-prose-docker-image)。 + +除非您对 Dockerfile 进行了修改并将其存储在其他位置，否则可以通过运行以下命令开始构建： + +```bash +docker build -t prose:latest -f api/deploy/Dockerfile api/ +``` + +这个命令搜索 `api/deploy/Dockerfile` 中的 `Dockerfile`，因为我们使用 `-f` 标志指示它在那里查找。 + +然后，它使用 `api/` 作为构建的工作空间，这使得 `Dockerfile` 中的引用正确解析。 + +通过传递 `-t prose:latest` 标签，将本地构建的镜像标记为最新构建。这对于在 Docker 环境中识别和管理镜像非常有用。 + +#### 拉取 Prose Docker 镜像 {#pull-the-prose-docker-image} + +如果您更愿意使用预编译好的 Prose 镜像的最新版本，只需运行： + +``` +docker pull kodefox/prose:latest +``` + +#### 运行 Prose Docker 容器 {#run-the-prose-docker-container} + +接下来，要运行新构建的镜像，请运行以下命令： + +```bash +docker run -d \ + -e PROSE_DISCOURSE_HOST=https://discourse.example.com \ + -e PROSE_APP_PORT=4000 \ + --name prose \ + -p 5000:4000 \ + kodefox/prose:latest +``` + +:::note +如果您手动构建了镜像，您需要将 `kodefox/prose:latest` 替换为您使用的镜像名称和标签，例如 `prose:latest`。 +::: + +小回顾一下，让我们简要地逐行解释一下这个命令。 + +**在 Detached 模式运行** + +```bash +docker run -d +``` + +第一行让 Docker 知道在 **detached模式** 下运行容器。 + +这意味着命令将在后台运行，不会与当前会话窗口绑定，并且即使您退出也会继续运行。 + +如果省略 `-d` 标志，Docker 将在前台运行容器，退出前台进程将停止容器。 + +**设置环境变量** + +```bash +-e PROSE_DISCOURSE_HOST=https://discourse.example.com +-e PROSE_APP_PORT=4000 +``` + +这些行设置 Docker 在运行容器时将环境变量 `PROSE_DISCOURSE_HOST` 和 `PROSE_APP_PORT` 传递给容器。 + +这两个都是应用级环境变量，Prose 本身将使用它们来正确运行。 + +Docker 镜像需要这些值被设置，并将它们传递给容器的环境，然后 Prose 通过 `process.env` 访问它们。 + +**为容器命名** + +```bash +--name prose +``` + +这一行告诉 Docker 为正在运行的容器命名。这使得通过命令更容易识别和与之交互，例如： + +```bash +docker stop prose +``` + +**配置主机和容器之间的端口映射** + +```bash +-p 5000:4000 +``` + +接下来，我们配置 Docker 的端口映射，这告诉 Docker 监听主机端口 `5000` 并将其映射到容器端口 `4000`。 + +因为我们之前设置了 `PROSE_APP_PORT=4000`，这意味着所有对主机端口 `5000` 的请求将被转发到容器内运行的 Prose 的端口 `4000`。 + +```bash +kodefox/prose:latest +``` + +命令的最后一行告诉 Docker 使用哪个镜像来运行容器。 + +如果您之前手动构建了 Prose 镜像，它将是您的镜像名称和标签，例如 `prose:latest`。 + +如果您选择从 Docker Hub 拉取，这只是告诉 Docker 如果本地没有此镜像时从哪里拉取镜像。 + +#### 下一步 {#next-steps} + +到此为止，您应该已经在主机上运行了 Prose 服务器的 Docker 容器。 + +但是，就准备将 Prose 主机部署到生产环境而言，您还没有完成。 + +接下来，我们将指导您完成最后几个步骤，完成 Prose GraphQL 服务器的部署。 + +#### 配置 SSL（重要） {#setup-ssl-important} + +:::danger +部署没有 SSL 的 Prose，以一种可以公开访问的方式是**极其危险**的。 + +这样做可能会您的 Discourse 站点及其所有数据的完全访问权限暴露给攻击者。 +::: + +在这一点上，**最重要的下一步**是为您的 Prose 主机配置 SSL 证书。 + +这么重要的原因是，没有 SSL，Prose 与 Discourse 之间的流量是未加密的。 + +这意味着攻击者可以窥探您的用户设备和 Discourse 之间的请求，包括重要的身份验证信息。 + +直截了当地说，部署 Prose 而没有配置 SSL 是不负责任的，会危及您的 Discourse 站点的安全。 + +攻击者甚至可以窃取您的身份验证令牌，并使用它访问甚至破坏您的 Discourse 站点。 + +#### 如何设置 SSL {#how-to-setup-ssl} + +有多种方法可以获得 SSL 证书。有些是免费的，有些是付费的。 + +免费的方法包括使用 [Let's Encrypt](https://letsencrypt.org/)，这是非常有用的，但可能需要更多的技术知识才能正确设置——取决于您的配置。一个关键的区别是您需要更频繁地更新证书。 + +付费的方法包括使用像 [DigiCert](https://www.digicert.com/) 这样的提供商来获得证书，这些证书的过期时间更长。 + +无论哪种方法，您最终都会获得证书文件，您可以配置并启动您的 Web 服务器。 + +理想情况下，此时您已经购买了一个域名。如果没有，我们建议使用域名提供商获取一个低成本的域名。 + +您可以将 Prose 托管在现有 Discourse 站点的子域上，例如 `prose.mydiscoursesite.com`。 + +或者，您可以只是获取一个便宜的、无意义的域名，例如 `purplemonkeydishwasher.tech`——因为您的用户通常不会看到它。 + +无论如何，在部署 Prose 到生产环境之前，**绝对不能**忽略准备好主机以加密 Prose 流量的重要性。 + +#### 确定如何在主机上公开 Prose {#determine-how-youll-expose-prose-on-the-host} + +当有人导航到运行 Prose 的主机时，他们的请求将如何路由到 Prose？ + +如果您直接在端口 80 上公开 Prose——**不推荐**——并且您的主机的域名是 `myproseserver.com`，那么用户将导航到 `http://myproseserver.com`，并看到[GraphiQL 界面](https://www.graphql-yoga.com/docs/features/graphiql)。 + +然而，更常见的方法是使用专用的 Web 服务器，如 Nginx 或 Apache，作为反向代理。 + +通过这种方法，Web 服务器监听您告诉它的所有端口，并配置为将流量路由到运行 Prose 的主机。 + +我们更高度推荐这种方法的原因如下： + +- 现有的 Web 服务器通常更可靠和高性能 +- 它允许配置 SSL 证书，这对保护您的用户数据是必要的 + +在配置 Web 服务器后，您需要指示它将流量转发到运行的 Prose 服务器。 + +您的设置可能如下所示： + +- Nginx 配置为在您的域名 `purplemonkeydishwasher.tech` 上监听端口 80 和端口 443 +- Nginx 已定位并加载了您的 `purplemonkeydishwasher.tech` 的 SSL 证书文件 +- Nginx 配置为将端口 80 上的所有请求重定向到端口 443 +- 您的 Prose 服务器在 Docker 中运行，端口为 80，并在主机上的端口 8080 上公开 +- 您的 Nginx 配置指定将 `purplemonkeydishwasher.tech` 的请求转发到端口 8080 +- 向 `purplemonkeydishwasher.tech`的请求，Nginx 将其路由到运行 Prose 的容器，Prose 处理请求并响应。 + +#### 配置云提供商的防火墙，如果有的话 {#configure-your-cloud-providers-firewall-if-one-exists} + +理想情况下，您已经配置了 Prose 以在开放互联网上公开，流量通过端口 443 加密。 + +但是，根据您的云提供商，您可能需要进入其设置，并在防火墙上公开该端口。 + +例如，在 DigitalOcean 中，这涉及到转到 Networking 部分，并创建一个新的防火墙规则。 + +添加常见端口，如 80 和 443，到防火墙是相当简单的。 + +之后，您只需将防火墙应用到您的特定实例，流量应该被允许通过。 + +#### 为您的域配置 DNS 设置 {#configure-dns-settings-for-your-domain} + +只要您已经注册了一个域名，您需要配置它，以便域名指向运行 Prose 的主机。 + +根据您的设置，这可能在您的域名服务商的设置面板中完成，或者可能在您的云服务商内部完成。 + +继续使用上面的 DigitalOcean 示例，您可以配置您的域名服务商指向 DigitalOcean 的域名服务器。 + +这实际上告诉您的域名提供商，DigitalOcean 将为您处理一切，并允许您从 DigitalOcean 内部进行域的调整。 + +在这种情况下，DigitalOcean 使将域名无缝映射到实例的 IP 地址，然后应该可以从域名访问它。 + +否则，您需要获取主机的 IP 地址，进入您的域名提供商，并指示它将对域名的请求转发到主机的 IP 地址。 + +#### 准备就绪 {#ready-to-go} + +到此为止，你的主机应该已经在正常运行 Prose 服务器了。当你访问你为 Prose 配置的域名时，你应该看到 Prose 在正常运行。 + +由于部署方式不同，我们理知道你的部署中有很多细节可能与此教程有较大出入。 + +如果在部署时遇到任何问题，请像往常一样不要犹豫联系我们寻求支持。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/deployment.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/deployment.md new file mode 100644 index 00000000..e737a238 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/deployment.md @@ -0,0 +1,86 @@ +--- +title: 概览 +--- + +正如[概念和架构](concepts#prose-discourse-through-graphql)中所介绍的，Prose是Lexicon的GraphQL API层，位于Discourse提供的传统RESTful API之上。 + +## 开始部署 {#getting-started-with-deployment} + +在这一点上，您可能会因以下两个原因而深入研究本文档的这一部分： + +- 您一直在针对运行Prose的本地实例（或容器）进行开发，现在准备将整个Lexicon项目部署到生产环境。 +- 您希望简化开发流程，将Lexicon移动应用程序指向部署的Prose实例。 + +无论哪种情况，本节的最终目标是在公开互联网上访问一个可用的Prose服务器。 + +### 🔐 关于访问控制的说明 {#-note-about-access-control + +这里提一下，Prose 无法暴露 Discourse 未公开的任何信息。 + +如果您的 Discourse 实例需要身份验证，则 Prose 将无法检索大多数查询，除非访问 Prose 的用户提供所需的身份验证信息。 + + +### 🧱 备选部署策略 {#-alternative-deployment-strategies} + +最初，我们希望提供一个集成部署策略的说明。这将涉及在与您的 Discourse 实例相同的主机上部署 Prose，并最好找到一种方法在 Discourse 使用的 Docker 主机内部部署和公开它。 + +这是可以实现的。但是我们选择专注于仅部署 Prose 作为专用实例。 + +不过我们也鼓励您自定义部署 Prose。 + +如果您选择这样做，并且遇到一些问题或挑战，请与我们联系。 + +理想情况下，我们可以帮助您解决问题，并将您的方法整合到我们的文档中，以便更多人从中受益。 + +## 部署为专用实例 {#deploying-as-dedicated-instance} + +如上所述，Prose 的官方部署策略是将其部署为专用实例。 + +这种方式同世间其他万物一样也有两面性，如下： + +### 🚀 优势 {#-benefits} + +Prose 的专用主机将具有更好的性能和可靠性，因为其唯一的资源使用来自运行 Prose。即，它有独占的 CPU、RAM、磁盘空间等。 + +另一方面，如果您设法将 Prose 部署在与运行 Discourse 实例相同的主机上，这意味着 Prose 和 Discourse 都需要共享主机分配的资源。如果您的 Discourse 实例已经在一个相当轻的主机上运行，那么在其上运行 Prose 可能意味着您需要升级到具有更多资源的主机。 + +### ⚠️ 可能的权衡 {#️-possible-trade-offs} + +#### 成本增加 {#increased-cost} + +当然，如果您设置专用主机来运行 Prose，则这将增加除了为托管 Discourse 而支付的费用的额外的成本。 + +话虽如此，对于大多数部署，您不太可能需要为 Prose 分配昂贵的资源。 + +例如，在 Digital Ocean 上，$5 的共享 CPU 节点通常就足够了。 + +#### 可能增加的延迟 {#potential-for-increased-latency} + +自然地，将 Prose 部署在与运行 Discourse 实例的不同主机上，会增加移动应用程序与 Discourse 之间的延迟。 + +这是因为每个请求都需要进行两次跳转： + +- 第一个请求是从客户端（您的 Lexicon 驱动的移动应用程序）到 Prose GraphQL API +- 第二个请求是从 Prose 到 Discourse + +然而，关于这一点最重要的问题是： + +- 量化具体有多少的延迟？ +- 这个延迟对我或我的用户来说是否明显缓慢？ + +当然，这取决于几个因素： + +- 您的 Discourse 服务器部署在哪里 +- 您的 Prose 服务器部署在哪里 +- 您的用户主要于在哪里 +- 如果流量（负载）对系统来说太多，无法使 Prose 和 Discourse 以最佳方式运行。 + +如果您观察到明显的延迟，我们建议您查看这些因素。 + +理想情况下，您将希望将 Prose 部署在与 Discourse 实例相同的区域；如果可以将 Prose 部署在与 Discourse 实例相同的数据中心，则更好。 + +## 接下来 {#up-next} + +有了这个概述，我们将首先向您介绍可能在部署 Prose 时可能需要或有用的所有[环境变量](env-prose)的列表。 + +最后，我们将深入其中，通过[准备您的主机和部署 Prose](dedicated)。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-features.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-features.md new file mode 100644 index 00000000..c2d3d6b9 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-features.md @@ -0,0 +1,54 @@ +--- +title: Discourse 特性支持 +--- + +下表展示了详细的 Discourse 特性及其在 **Lexicon 移动应用** 中的支持情况。 + +如果我们遗漏了某个特性，或者这里的任何内容看起来已经过时，请随时提交一个 Pull Request 来更新表格。 + +你所喜欢的特性没有被支持？[联系我们](mailto:support@kodefox.com)来探讨如何将需求变成现实。 + +#### 我们对特性支持的一般原则 {#our-general-approach-to-feature-support} + +我们最初的重点是用户侧功能，而不是管理侧功能。 + +例如，用户可以为他们的主题选择话题，但管理员无法从移动应用中创建新的话题类别。 + +所以，大多数管理任务最好还是在桌面设备上使用 Discourse 网页应用完成。 + +### Lexicon 移动端特性 {#lexicon-mobile-app-features} + +| 特性 | 描述 | 支持状态 | 备注 | +| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- | +| 消息推送
Lexicon version 2 | 接收来自回复、提及、喜欢等操作的消息推送| ✅ 🔧 | Must have the [Lexicon Discourse Plugin](./discourse-plugin.md) installed and configured | +| 邮件深度链接
Lexicon version 2 | 通过 Discourse 邮件中的话题或帖子链接打开移动端 APP | ✅ 🔧 | Must have the [Lexicon Discourse Plugin](./discourse-plugin.md) installed and configured | +| 登陆两步验证 | 允许用户在登陆时可选地使用两步验证 | ✅ | Managing 2FA, such as enabling it or disabling it from within the app, is not currently supported | +| 为话题添加标签 | 创建并为话题添加 tag 以提供相关信息 | ✅ 🔧 | Configuration required: see [Optimal Experience](optimal#enable-topic-tagging) | +| 话题摘要 | 在主页展示话题中第一个帖子的摘要 | ✅ 🔧 | Configuration required: see [Optimal Experience](optimal#enable-topic-excerpts) | +| 查看用户活动 | 查看用户的最近活动，例如最近发帖或点赞 | ✅ | The ability to filter by activity is not currently supported | +| 话题互动 | 喜欢，查看，回复，最常回复者 | ✅ | | +| 话题和帖子操作 | 点赞或修改话题或帖子 | ✅ | | +| 查看置顶或最新话题 | 提供一个可切换的开关在主页顶部显示最新发帖或最火发帖 | ✅ | | +| 搜索 | 在当前 Discourse 站点上搜索关键词，分类或者标签 | ✅ | | +| 分类目录 | 查看话题的分类目录，并根据勾选的分类筛选帖子 | ✅ | Categories cannot be created, updated, or deleted | +| 向帖子中添加媒体素材或附件 | 用户可以在发帖时添加一些本地的媒体素材，图片或视频等 | ✅ 🔧 | Configuration recommended for supported file extensions-see [Optimal Experience](optimal#configure-upload-extensions) | +| 标准 Markdown 支持 | 在移动端 APP 发帖时，可以使用标准 Markdown 并正常渲染 | ✅ | Light, incomplete support exists for some of Discourse's custom markup, such as dates | +| 注册 | 允许用户直接在移动端 APP 上注册新账户。能否注册同时也受到你的站点本身是否允许注册影响 | ✅ | | +| 访问公开站点 | 用户可以直接在移动 APP 上访问你的公开 Discourse 站点 | ✅ | Users will be prompted to login upon attempting an authenticated action | +| 用户信息 | 可以查看他人的个人资料或修改自己的个人资料 | ✅ | Partial support: displays the user's photo, username, Markdown bio on a single line, and recent activity | +| 举报帖子 | 用户可以举报发帖存在异常，管理员将会审核被举报的内容 | ✅ | Admins are not able to review posts in the app, though they will see in-app notifications for flags | +| 应用内通知 | 用户可以在应用内的个人资料处查看最新的消息通知，并可以将所有信息标为已读 | ✅ | Some notifications from Discourse are not tappable in the mobile app, such as badge notifications | +| 私人消息 | 用户可以向他人或群组发送私信 | ✅ | | +| 提及他人 | 用户可以在发帖或发私信时提及(@)他人 | ✅ | +| 主题色彩 | Provides light and dark mode support for users | ✅ | Specify color scheme (light mode, dark mode, or system) from within the app (only local to the user's mobile device) | +| 消息红点 | The ability to see and interact with badges that have been awarded to users on the Discourse instance | ❌ | | +| 发帖草稿 | Enable users to start composing a draft of a post and return to it later | ❌ | | +| 群组 | Enable users to create and participate in private groups of which only group members can view certain topics | ❌ | | +| 管理员功能 | Discourse admin features generally not available in Lexicon—better suited to a desktop environment | ❌ | Editing posts is supported | +| 发帖引用, 投票, 切换开关，任务列表 | Custom text formatting that enables Discourse-specific features | ❌ | | +| Discourse 表情 | Utilize emojis when creating a topic, making a post, or sending a reply | ❌ | Standard unicode-based emojis are supported | +| 收藏/添加书签 | Allow users to bookmark certain posts or topics | ❌ | | +| DiscourseConnect (SSO) | Replace Discourse authentication with a Custom Provider | ❌ | | +| Custom Authentication Plugins | Login via OAuth2 or other protocols using custom Discourse Plugins | ❌ | | +| 在线聊天 | Enable users to initiate conversations using the chat feature, either in a channel or through private messaging | ❌ | | +| 用户消息状态 | Allow other user in community to see user message status | ❌ | | diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin-enable.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin-enable.md new file mode 100644 index 00000000..1c5fc55d --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin-enable.md @@ -0,0 +1,32 @@ +--- +title: 启用 Lexicon 插件 +slug: discourse-plugin/enable +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +--- + +在你确认插件已经安装并 Discourse 实例已经重新运行后，你可以按照以下步骤启用插件： + +1. 作为管理员用户，访问你的 Discourse 管理面板。 +2. 导航到 `插件` 选项卡。 + + 你会注意到 `discourse-lexicon-plugin` 还没有启用。 + + 插件管理页面 + +3. 点击 `discourse-lexicon-plugin` 条目旁边的 `设置` 按钮。 +4. 选择你想要启用的功能并打开它。 + +##### 推送通知 {#push-notifications} + +对于推送通知插件，你只需要勾选 `lexicon push notifications enabled` 复选框。这在[启用推送通知](./push-notifications/setup/enable-push-notifications.md)中有详细介绍。 + +##### 电子邮件深度链接 {#email-deep-linking} + +对于电子邮件深度链接，你需要在启用之前先填写你的应用 scheme。 + +Plugin Settings Page + +这部分内容在[启用电子邮件深度链接](./email-deep-linking/setup/enable-email-deep-linking.md)中有详细介绍。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin-installation.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin-installation.md new file mode 100644 index 00000000..6fbff0d8 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin-installation.md @@ -0,0 +1,82 @@ +--- +title: 安装插件 +slug: discourse-plugin/setup +--- + +在你开始使用 Lexicon Discourse 插件之前，你需要完成一些先决条件和安装步骤。本文档将指导你完成这些步骤，确保插件在你的站点上顺利设置。 + +## 先决条件 {#prerequisites} + +为了使用这个插件，你必须能够访问你的 Discourse 服务器，以一种允许你修改服务器的 `app.yml` 的方式。如果有一个托管提供商为你管理 Discourse。你需要联系他们帮你安装插件。 + +具体来说，你需要安装插件的能力，这意味着直接修改 `/var/discourse/containers/app.yml` 来添加 [Lexicon Discourse 插件](https://github.com/lexiconhq/discourse-lexicon-plugin.git), 修改之后你需要重新构建 Discourse 站点. + +## 插件安装步骤 {#plugin-installation-steps} + +### 访问你的服务器 {#access-your-server} + +通过 SSH 登录到你的 Discourse 主机服务器。 + +不同的设备登陆方式不一样，但通常你需要使用终端应用程序，如 macOS 上的 Terminal 或 Windows 上的 PuTTY。 + +### 打开 Discourse `app.yml` 文件 {#open-the-discourse-appyml-file} + +使用你喜欢的终端编辑器（vim、emacs、nano 等）打开 `app.yml` 文件。 + +:::note +你可能需要 `sudo` 权限来编辑文件，但这取决于服务器的配置。 +::: + +```bash +vim /var/discourse/containers/app.yml +``` + +### 获取插件的 Git Clone URL {#get-the-plugins-git-clone-url} + +Discourse 插件通过可访问的 Git Clone URL 引用，通常以 `.git` 结尾。 + +[Lexicon Discourse 插件](https://github.com/lexiconhq/discourse-lexicon-plugin)的 Git Clone URL 如下： + +``` +https://github.com/lexiconhq/discourse-lexicon-plugin.git +``` + +将其复制到剪贴板，以便在下一步中使用。 + +### 将插件的仓库 URL 添加到你的容器的 `app.yml` 文件中： {#add-the-plugins-repository-url-to-your-containers-appyml-file} + +将插件的 Git Clone URL 添加到如下的部分。 + +``` +hooks: + after_code: + - exec: + cd: $home/plugins + cmd: + - git clone https://github.com/lexiconhq/discourse-lexicon-plugin.git +``` + +### 重新构建容器，谨慎操作 {#rebuild-the-container-with-caution} + +:::caution +请注意，重新构建你的站点将导致你的站点在一段时间内下线，通常在 5 到 30 分钟之间。我们建议谨慎操作，并采取下面列出的预防措施。 +::: + +#### 预防措施 {#precautionary-measures} + +1. 在安装插件或执行任何站点重建之前，强烈建议创建 Discourse 站点的备份。 +2. 在尝试安装此插件之前，建议将 Discourse 安装和所有现有插件升级到最新版本。 +3. 尽管很少见，但可能会出现站点在重建过程后无法上线的情况，需要进一步排查才能恢复。 + - 安装插件或执行任何需要重建应用的任务总会存在风险。 + - 我们建议您在最小化受影响用户的时间进行这些更改，并在出现问题时有一个明确的应急计划。 + +#### 运行重建命令 {#run-rebuild-command} + +```bash +cd /var/discourse +./launcher rebuild app +``` + +### 如何卸载插件 {#how-to-uninstall-the-plugin} + +要删除插件，只需从你的 `app.yml` 文件中删除 Git 克隆 URL 行，并重新构建你的站点。请记住，重新构建你的站点将导致你的站点在一段时间内下线，并伴随着一些风险。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin.md new file mode 100644 index 00000000..fa5a706c --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/discourse-plugin.md @@ -0,0 +1,15 @@ +--- +title: 简介 +slug: discourse-plugin/ +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +--- + +从 Lexicon 版本 2.0.0 开始，我们提供了一个自定义 Discourse 插件，以提供更无缝的移动集成体验，让 Discourse 和你的 Lexicon 移动应用之间的交互更加流畅。 + +插件目前提供了两个关键功能： + +- **推送通知**：根据你的 Discourse 站点上的相关活动，支持用户移动设备上的原生推送通知。由 Expo 的 [推送通知服务](https://docs.expo.dev/push-notifications/overview/) 提供支持。 +- **电子邮件深度链接**：Discourse 邮件中的自定义深度链接，允许用户直接从他们的移动电子邮件客户端无缝启动你的 Lexicon 移动应用。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/intro.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/intro.md new file mode 100644 index 00000000..a0aa08a8 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/intro.md @@ -0,0 +1,9 @@ +--- +id: intro +title: 简介 +slug: discourse-plugin/email-deep-linking +--- + +Lexicon Discourse 插件提供了支持，用于将 Discourse 的电子邮件通知与您的 Lexicon 手机应用集成。我们的插件修改了特定 Discourse 电子邮件中的链接，以便在用户点击相关链接时在 Lexicon 手机应用上打开相关主题或帖子。如果没有安装应用的话，它将和常规一致回到在设备的 Web 浏览器中打开主题。 + +本文档的这一部分提供了逐步说明，以将电子邮件深度链接集成到您的 Discourse 站点中，以便您的用户在 Lexicon 手机应用中拥有更无缝的体验。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md new file mode 100644 index 00000000..4a1828ad --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md @@ -0,0 +1,29 @@ +--- +title: 启用电子邮件深度链接 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +本指南将引导您完成在 Discourse 站点上激活电子邮件深度链接所需的步骤。 + +## 步骤 {#steps} + +1. 确保已安装并激活[Lexicon Discourse 插件](../../discourse-plugin-installation.md)。 +2. 访问您的 Discourse 管理面板。 +3. 导航到 `插件` 部分。 + + + +4. 找到 `discourse-lexicon-plugin` 并单击 `设置` 按钮。 +5. 在 `lexicon app scheme` 设置中填写您的应用 scheme。必须填写应用 scheme 才能启用电子邮件深度链接。 +6. 在 Lexicon 设置部分中选中 `启用电子邮件深度链接` 复选框并保存更改。 + + + +启用电子邮件深度链接功能后，您将能够在您的 Discourse 实例中使用其功能。 + +具体来说，当您的用户收到新消息或帖子的电子邮件通知时，链接将被覆盖以重定向到 Lexicon Discourse 插件中的自定义端点。 + +如果用户在移动设备上已安装了您的 Lexicon 手机应用（根据您指定的应用 scheme），页面将尝试打开应用并重定向到相关消息或帖子。 + +否则，页面将回退到 Discourse Web 应用程序中的消息或帖子的默认行为。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md new file mode 100644 index 00000000..0b630332 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md @@ -0,0 +1,51 @@ +--- +title: 验证电子邮件深度链接 +slug: verify-email-deep-linking +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +:::note +以下步骤假定**您已经发布了 Lexicon 手机应用**到 App Store 和/或 Google Play Store**并且具有正确的应用 scheme**。如果您在本地通过 Expo 在您的设备上运行应用程序，这些步骤将无法能够正常工作。 +::: + +本指南将提供逐步说明，以帮助您验证 Lexicon 手机应用中的电子邮件深度链接功能。 + +## 前提条件 {#pre-requisites} + +:::note +如果您尚未满足以下所有先决条件，则此测试将无法按预期工作。 +::: + +为了正确测试电子邮件深度链接： + +1. 您**必须**已经将 Lexicon 手机应用发布到 App Store 和/或 Google Play Store。 +2. 您已经安装并配置了 Lexicon Discourse 插件在您的 Discourse 站点上。 +3. 您已经在 Lexicon Discourse 插件设置中启用了电子邮件深度链接，并且应用 scheme 与您发布的应用程序匹配。 +4. 您至少有 1 部已经安装了您的 Lexicon 手机应用的移动设备，并且具有与 Discourse 中配置的正确应用 scheme。 +5. 您至少有 2 个不同的 Discourse 帐户进行测试。 +6. 确保您的 Discourse 站点允许**邮件列表模式**，并且已为您要测试的帐户打开。 + - 如果您没有这样做，您将需要等待 Discourse 发送其下一个摘要电子邮件，这可能需要一段时间。 + +## 步骤 {#steps} + +为了在您的**已发布** Lexicon 手机应用中测试电子邮件深度链接，请按照以下步骤操作： + +1. 确保您在您的 Discourse 实例上至少有 2 个不同的帐户。 +2. 在您的移动设备上，打开您的 Lexicon 手机应用并使用其中一个帐户登录。 + - 我们将这个帐户称为**第一个**帐户。 + - **注意**：确保您的移动设备上的电子邮件客户端将为此帐户接收电子邮件。 +3. 在您的笔记本电脑或台式电脑上的 Web 浏览器中打开您的 Discourse 站点。 +4. 使用您的**第二个** Discourse 帐户登录到您的 Web 浏览器。 +5. 在您的移动设备上，使用**第一个**帐户创建一个新帖子。 +6. 现在，在您的笔记本电脑或台式电脑上，使用**第二个**帐户找到您在移动应用程序中创建的帖子并回复。 +7. 回到您的移动设备，您应该会收到来自 Discourse 的关于第二个帐户回复的电子邮件通知。 +8. 点击 `Visit Message` 或 `Visit Topic` 按钮。 + - 标签取决于生成电子邮件的活动（请参见下面的屏幕截图）。 +9. 链接将首先在您的移动 Web 浏览器中打开。只要 Lexicon 手机应用已安装并匹配配置的应用 scheme，它应该会自动打开您的应用程序到相关主题或消息场景。 + +
+ +
+ +如果您的 Lexicon 手机应用成功打开并重定向到相关主题或消息，恭喜！您已成功验证了 Lexicon 手机应用中的电子邮件深度链接功能。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/env-mobile.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/env-mobile.md new file mode 100644 index 00000000..34e87e57 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/env-mobile.md @@ -0,0 +1,119 @@ +--- +title: 配置变量 +--- + +您可以在 `frontend/Config.ts` 中检查和配置变量。 + +下表描述了 Lexicon 移动应用的可配置变量。 + +如果有默认值指示，如无需要则您无需设置它。 + +| 变量 | 是否必须 | 备注 | 默认值 | 示例值 | +| -------------------- | -------- | -------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| proseUrl | Yes | Prose Server 的url地址 (必须以 http 或 https 开始) | - | https://prose.myserver.com https://prose.myserver.com:8080 https://prose.myserver.com/subpath https://prose.myserver.com:8080/subpath | +| inferDevelopmentHost | No | 是否使用开发设备的地址覆盖默认的 localhost 地址 | (empty) | true | + +## `config` 对象 {#the-config-object} + +在 `Config.ts` 文件中，您会找到一个 `config` 对象，它允许您根据场景指定配置值。 + +主要有两种场景： + +- `localDevelopment`：在本地开发应用时使用。这个配置也是未知构建通道情况下的默认选项。 +- `buildChannels`：在使用 EAS CLI 构建应用时，用于定义构建通道的配置。 + +一般情况下您只需关心为这些部分配置 `proseUrl`。 + +## `proseUrl` {#proseurl} + +:::caution +`proseUrl` 必须始终指定，无论是否包含端口号，且必须始终以 `http://` 或 `https://` 开始。 +::: + +`proseUrl` 用于指定 Prose GraphQL API 的 URL。 + +Prose GraphQL API 充当 Lexicon 移动应用和您的 Discourse 站点之间的传话人。没有它，移动应用无法与您的 Discourse 站点进行交互。 + +### 示例 {#example} + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com', + }, + production: { + proseUrl: 'https://prose.myserver.com', + }, + }, +}; +``` + +借助上述配置，应用将： + +- 在使用 `npm run start` 运行应用时，指向 `http://localhost:8929` +- 在使用 `eas build --profile preview` 构建应用时，指向 `https://preview.myserver.com` +- 在使用 `eas build` 构建应用时，指向 `https://prose.myserver.com` + +`proseUrl` 也可以包含子路径： + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com:8080/subpath', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +**在开发环境中的不同行为** + +在本地运行应用时，如果 `proseUrl` 设置为 `http://localhost` 或 `http://127.0.0.1`，它将使用 Expo 的 `debuggerHost` 常量将 `proseUrl` 替换为您的开发机器的 IP 地址。 + +_注意：构建应用时不适用此规则。_ + +这解决了多个问题： + +- 从 Android 模拟器内部访问 `localhost` 不会映射到您的开发设备 +- 从运行 Expo Go 的设备访问 `localhost` 不会映射到您的开发设备 + +否则，这两种情况都需要您手动识别和指定开发设备的 IP 地址。但这很麻烦，因为您的机器的 IP 地址可能总在变化。 + +如果你想了解更多关于这个的细节，可以查看 `frontend/constants/app.ts` 中的实现。 + +如果您不希望这种行为发生，可以使用 `inferDevelopmentHost` 标志禁用它。 + +## `inferDevelopmentHost` {#inferdevelopmenthost} + +:::info +此标志仅在 `localDevelopment` 下有效。在 `buildChannels` 中使用时不起作用。 +::: + +在开发时，默认情况下，Lexicon 移动应用会检查 `proseUrl` 是否设置为 `http://localhost` 或 `http://127.0.0.1` . + +当检测到这两个值中的任何一个时，它们将被覆盖为您的开发设备的 IP 地址。 + +这是一个非常有用的功能，使得在设备上测试可以直接工作，而无需手动指定您的 IP 地址（或在更改时更新它）。 + +对于不希望这种行为发生的情况，`inferDevelopmentHost` 可以用作标志来禁用此行为。可以通过指定值 `false` 来禁用它。 + +当设置为 `false` 时，将不再发生覆盖 `proseUrl` 为开发设备的 IP 地址的行为，原始值将原样传递。 + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + inferDevelopmentHost: false, + }, +}; +``` diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/env-prose.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/env-prose.md new file mode 100644 index 00000000..cf634bc4 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/env-prose.md @@ -0,0 +1,15 @@ +--- +title: Prose 环境变量 +--- + +下表列出了 Prose GraphQL API 的环境变量。 + +若有默认值指示，无需要的情况下您无需显式设置它。 + +| Environment Variable | Required | Notes | Default Value | Example Value | +| --------------------------- | -------- | ----------------------------------------------------------------------------------- | ---------------------- | ------------------------------------ | +| PROSE_DISCOURSE_HOST | Yes | 需要与 Prose 连接的 Discourse 站点的地址 | - | https://discourse.example.com | +| PROSE_DISCOURSE_UPLOAD_HOST | No | 为 Prose 配置一个不同于 Discourse 站点的附件服务器. | | https://upload.discourse.example.com | +| PROSE_APP_HOSTNAME | No | Prose 在应用层监听的地址。（Lexicon APP 通过此地址连接到 Prose） | localhost | 0.0.0.0 | +| PROSE_APP_PORT | No | Prose 在应用层监听的端口。 Lexicon APP 通过此端口连接到 Prose）| 80 | 8080 | +| SKIP_CHECK_DISCOURSE | No | 跳过 Prose 启动时对 Discourse 可访问性的检测。 | false | true | diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/intro.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/intro.md new file mode 100644 index 00000000..c41c1828 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/intro.md @@ -0,0 +1,142 @@ +--- +id: intro +title: 简介 +slug: / +--- + + + --- iOS Auth + + + + --- iOS Dark Mode + + + + --- iOS Comment + + + + --- iOS Message + + --- Android Auth + + + + --- Android Dark Mode + + + + --- Android Comment + + + + --- Android Message + + + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Carousel from 'react-bootstrap/Carousel'; + +--- + +Lexicon 是一款基于[Discourse](#what-is-discourse)构建的，可定制的预建移动应用程序，可以提供优雅的移动讨论体验。 + +## 特性 {#features} + +- 主题、私信、用户注册、资料管理等功能 +- 为现有 Discourse 站点快速创建 Android 和 iPhone 应用程序 +- 将[推送通知](./push-notifications/introduction.md)直接发送到用户的移动设备上 +- 通过[电子邮件深度链接](./email-deep-linking/intro.md)获得更无缝的原生 Discourse 体验 +- 为您的品牌[定制应用程序](white-labeling) +- 由 [GraphQL](https://graphql.org/) API 提供支持 +- 免费开源！ +- 提供[商业支持](commercial-support) + +## 优势 {#benefits} + +- 启动自定义的 Discourse 移动应用 +- 通过添加以移动为先的 Discourse 来优化用户的互动体验——不再需要[WebViews](https://www.kirupa.com/apps/webview.htm)。 +- 使用 [React Native](https://reactnative.dev/) 和 [Expo](https://expo.io) 构建，为 iOS 和 Android 提供原生外观和体验。 +- 包含一个自动文档化的[GraphQL](https://graphql.org/) [接口](concepts#prose-discourse-through-graphql)，您可以在其上构建 Discourse 应用。 + +## 应用展示 {#screenshots} + +### iOS {#ios} + + + + IOS Lexicon Login Page + IOS Lexicon Signup Page + IOS Lexicon Home Page + + + IOS Lexicon Dark Mode in Home Page + IOS Lexicon New Post Page + IOS Lexicon Post Detail Page + + + IOS Lexicon Comment Section + IOS Lexicon Profile Page + IOS Lexicon Notification Page + + + IOS Lexicon Message Page + + + +### Android {#android} + + + + Android Lexicon Login Page + Android Lexicon Signup Page + Android Lexicon Home Page + + + Android Lexicon Dark Mode in Home Page + Android Lexicon New Post Page + Android Lexicon Post Detail Page + + + Android Lexicon Comment Section + Android Lexicon Profile Page + Android Lexicon Notification Page + + + Android Lexicon Message Page + + + +## Lexicon如何运行? {#how-does-lexicon-work} + +Lexicon通过**两个关键组件**提供原生移动Discourse体验： + +- [**Lexicon移动应用**](#the-lexicon-mobile-app) - 使用[Expo](https://expo.io)和[React Native](https://reactnative.dev/)构建的现代移动应用 +- [**Prose**](#prose-discourse-through-graphql)，基于Discourse API 的 GraphQL API + +### Lexicon移动应用 {#the-lexicon-mobile-app} + +Lexicon移动应用使用[Expo](https://expo.io)构建，这使我们可以使用单个代码库维护iOS和Android应用。 + +对于不熟悉的人，Expo提供了在[React Native](https://reactnative.dev/)之上提供优越的开发和部署体验。 + +### Prose: Discourse 之上的 GraphQL {#prose-discourse-through-graphql} + +Prose 是 Lexicon 构建在Discourse的API之上的[GraphQL](https://graphql.org/)层. + +这使开发人员可以快速构建基于现有 Discourse 站点的应用程序，同时利用[GraphQL的优势](https://www.apollographql.com/docs/intro/benefits/)。 + +### 什么是Discourse? {#what-is-discourse} + +Discourse是一款开源的**讨论软件**，设计简单，易于设置，维护良好。 + +您可以在[Discourse网站](https://www.discourse.org/)上了解更多。 + +### 其他细节 {#further-details} + +您可以在[概念与架构](concepts)中了解我们方法的技术细节。 + +## 开源协议 {#license} + +MIT. Copyright (c) [Lexicon](https://github.com/lexiconhq) diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/lexicon-updates.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/lexicon-updates.md new file mode 100644 index 00000000..4adf0606 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/lexicon-updates.md @@ -0,0 +1,17 @@ +--- +title: 接收来自 Lexicon 的更新 +--- + +考虑到本项目的性质，同步修复错误、更新和其他更改到 Lexicon 移动应用的最佳方法是将您的应用视为我们存储库的一个 fork 。 + +在为您的需求定制 Lexicon 移动应用的过程中，您可能会对主题或资源进行任意数量的更改。 + +然而，基础代码库应该在很大程度上保持不变。 + +这意味着，当我们在 `master` 分支上发布一个 bugfix 或新功能时，您可以拉取我们的更改，解决与您的更改的冲突，并准备好重新发布您的应用的更新版本。 + +使用 Git 可以简单并高效地解决这个问题，但值得一提此方法还有改进的空间。 + +如果有足够的兴趣，我们可能会决定将 Lexicon 形成更多独立的 SDK 包，您可以通过 npm 导入并接收更新。 + +如果您对这个想法感兴趣，请联系我们！ diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/optimal.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/optimal.md new file mode 100644 index 00000000..f78c96d9 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/optimal.md @@ -0,0 +1,98 @@ +--- +title: 优化 +--- + +如果你打算使用 Lexicon 移动应用，你需要对 Discourse 站点进行一些调整，以为用户提供最佳的应用体验。 + +## 安装 Lexicon Discourse 插件 {#install-the-lexicon-discourse-plugin} + +Lexicon Discourse 插件通过两种关键方式增强了用户的原生移动体验： + +- 添加了对推送通知的支持 +- 添加了对电子邮件深度链接的支持。 + +你可以在[这里](./discourse-plugin.md)阅读有关插件的更多信息以及如何设置它。 + +## 启用主题摘要 {#enable-topic-excerpts} + +我们设计了移动应用，以便用户在滚动主题列表时可以轻松地看到主题的前几句话。 + +然而，默认情况下，Discourse 在列出主题时不会返回摘要。 + +还好有一个秘密设置可以启用这个功能。 + +只需要一点额外的配置就可以启用。 + +因为 Discourse 允许用户选择是否启用这个功能作为一个[主题组件](https://meta.discourse.org/t/topic-list-excerpts-theme-component/151520)，我们想引导你通过切换设置中的选项。 + +如果你更喜欢使用上面的主题组件来启用它，你也可以这样做。 + +要想打开这个设置需要能够访问服务器并更改其中的设置。 + +### 说明 {#instructions} + +原版的说明可以在[这里](https://meta.discourse.org/t/discourse-as-a-simple-personal-blog-engine/138244/4)找到。 + +首先，进入服务器，并进入正在运行的 Discourse 应用。 + +```sh +$ /var/discourse/launcher enter app +``` + +接下来进入 Rails CLI: + +```sh +$ rails c +``` + +最后将这个设置改成 `true`: + +```sh +$ SiteSetting.always_include_topic_excerpts = true +``` + +操作完成之后就可以退出了，现在应用中应该可以看到摘要了。 + +## 启用主题标签 {#enable-topic-tagging} + +Lexicon 移动应用设计时考虑到了标签的使用。 + +这使用户可以查看和管理主题上的标签，这是许多 Discourse 服务器上的热门功能。 + +不幸的是，默认情况下这个功能是关闭的。 + +### 说明 {#instructions-1} + +为了启用它，你可以采取以下步骤： + +- 导航到 `/admin/site_settings` 页面 +- 使用搜索栏搜索 `tagging enabled` 设置 +- 确保它被选中 +- 如果你做了更改，点击绿色的复选框按钮来应用它 + +现在应该可以给主题加标签了，并且可以在应用中查看。 + +## 配置可上传文件限制 {#configure-upload-extensions} + +Discourse 提供了一个安全功能，允许 Discourse 管理员指定他们的用户可以上传的文件扩展名白名单。 +例如，大多数管理员会选择限制上传 `.exe` 文件。 +为了与你的 Discourse 实例的设置兼容，Lexicon 移动应用简单地请求允许的文件的扩展名列表，并使用它来在应用中强制执行通过扩展名筛选文件。 +默认情况下，大多数 Discourse 实例支持这个默认的扩展名列表： + +- `.jpg` +- `.jpeg` +- `.png` +- `.gif` +- `.heic` +- `.heif` + +如果你想调整 Discourse 站点中的文件扩展名列表，你可以按照以下说明进行操作。 + +### 调整 Discourse 中允许的文件扩展名 {#adjusting-allowed-extensions-in-discourse} + +- 导航到 `/admin/site_settings` 页面 +- 使用搜索栏搜索 `extensions` 设置 +- 找到标记为 `authorized extensions` 的设置 +- 根据需要调整列表，包括你希望用户能够上传的文件扩展名 +- 当你完成更改后，点击绿色的复选框按钮来应用它们 +- Lexicon 移动应用将从你的站点设置中接收到更新的扩展名列表，并开始为你的用户强制执行它。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/play-store.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/play-store.md new file mode 100644 index 00000000..94691800 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/play-store.md @@ -0,0 +1,167 @@ +--- +title: 发布到谷歌应用商店 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## 前提 {#prerequisites} + +:::note +如果你还没有 Google 开发者账户，需要注意的是，创建一个账户是需要付费的。 +::: + +- 拥有[Google 开发者账户](https://play.google.com/console/signup) 用于访问 [Google Play 控制台](https://play.google.com/console) +- 拥有 Expo 账户 +- EAS CLI 2.6.0 或更新版本 +- [Lexicon Discourse 插件](./discourse-plugin.md)已经安装在你的 Discourse 站点上 + +## Google Play Console {#google-play-console} + +[Google Play 控制台](https://play.google.com/console)允许你设置你的应用、邀请测试人员，并将你的应用发布到[Google Play 商店](https://play.google.com/store)。 + +由于你正在发布一个使用 Expo 构建的应用，**非常重要**的是，你要按照[Expo的说明](https://github.com/expo/fyi/blob/master/first-android-submission.md) 正确提交应用到 Google Play 商店。 + +## 配置应用 {#app-configuration} + +在 Google Play 控制台中设置应用之后，还有一些其他的调整需要做。 + +### 构建配置 {#build-config} + +与[发布到 App Store](app-store)的方法类似，如果你还没有设置应用名称和 slug，你需要在 `frontend/app.json` 中设置。[slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) 用作 Expo 网络服务中应用的 URL 的一部分，建议使用 kebab-case（例如，`my-lexicon-app`）。 + +:::info +请注意，下面的样例也包含了 `scheme`。如果你想在你的应用中支持 [电子邮件深度链接](./email-deep-linking/intro.md)，**你必须指定一个 scheme**，然后使用相同的 scheme 配置 Lexicon Discourse 插件 +::: + +```json +"name": "", +"slug": "", +"scheme": "", +``` + +然后，在 `frontend/` 目录运行以下命令来配置 EAS Build，或者跳到下一步： + +```bash +eas build:configure +``` + +EAS CLI 会提示你指定 `android.package` 和 `ios.bundleIdentifier`，如果这些值在 `app.json` 中尚未提供的话。 + +接下来，验证 `app.json` 中的 `android` 部分是否包含了你的应用的 `package` 名称和其他特定于你的应用的细节。请注意，当你使用 `production` 配置构建应用时，`versionCode` 将会自动更新，所以你不需要手动递增版本号。 + +此外，根据你的应用权限，你可能需要添加更多的细节。 + +在下面的示例中，我们为我们的应用提供了读写外部存储的权限。 + +```json + "android": { + "package": "", + "permissions": [ "READ_EXTERNAL_STORAGE" , "WRITE_EXTERNAL_STORAGE" ], + "versionCode": 1, + }, +``` + +如果你的应用需要更多的权限，请确保在配置中按需指定。 + +如果你还不太了解权限是如何工作的，最好查看[Expo文档](https://docs.expo.io/versions/latest/sdk/permissions)上关于这个主题的内容，以便全面了解。 + +### 配置 Config 值 {#setup-config-values} + +:::info +当你发布应用时，需要将 Prose 部署到一个可公开访问的地方，比如 AWS 或 DigitalOcean 这样的云托管服务商。如果 Prose 只在你的本地机器上运行，那么下载你的应用的用户将无法使用它。 + +如果你还没有部署 Prose，请查看[此文档](deployment)。 +::: + +接下来，在 `Config.ts` 中为你的构建配置 **Prose URL**。你可以为每个构建通道设置不同的 URL。 + +:::note +在 Lexicon 的原始版本中，**Prose URL** 是在 `frontend/.env` 中指定的。不过，作为迁移到 Expo 的 EAS 功能的一部分，我们将配置集中到了 `frontend/Config.ts` 中，以免你需要在多个地方维护它，正如[Expo 文档](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update)中所建议的那样。 +::: + +```ts +const config = { + // ... + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, +}; +``` + +### 添加 Play Store 秘钥文件 {#add-the-play-store-secret-file} + +在最后一步，你需要提供一个包含私钥的 `.json` 文件，以便与 Play Store 交互。按照[这个指南](https://github.com/expo/fyi/blob/main/creating-google-service-account.md)生成密钥。然后，将 JSON 文件复制到你的 `lexicon/frontend` 目录，并将文件重命名为 `playstore_secret.json`。 + +JSON 文件看起来像这样： + +```json +{ + "type": "service_account", + "project_id": "", + "private_key_id": "", + "private_key": "-----BEGIN PRIVATE KEY----------END PRIVATE KEY-----\n", + "client_email": "", + "client_id": "", + "auth_uri": "", + "token_uri": "", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/lexicon%40api.iam.gserviceaccount.com" +} +``` + +## 构建安卓应用 {#build-your-app} + +因为我们使用的是 Expo 和 React Native，所以这一步与为 iOS 构建应用并没有太大的不同。 + +从 `frontend/` 目录运行以下命令，以在发布之前检查应用： + +```bash +eas build --platform android --profile preview +``` + +运行 `eas build` 命令时，使用 `preview` 配置文件将会构建 APK 文件。这样你就可以快速将它加载到你的 Android 设备或模拟器上。构建完成后，转到 [Expo 网页控制台](https://expo.dev) 中的项目，然后点击屏幕左侧的 **Builds** 菜单。 + +- 点击你想要安装的项目。 + + Builds + +- 在 `Build Artifact` 部分按下 `Install` 按钮下载应用。 + + Build Artifact + +你可以下载并在真实设备上运行应用，或者将下载的 APK 文件拖到模拟器上运行。 + +验证应用按预期运行后，就可以继续构建发布版本： + +```bash +eas build --platform android --profile production +``` + +生成生产版本的步骤与生成预览版本的步骤类似。不过，与预览版本不同的是，你无法在 Android 模拟器中启动生产版本，它仅用于发布到 Play Store。 + +构建完成之后，你可以继续提交到 Play Store。 + +## 发布到 Play Store {#publish-to-the-play-store} + +在这一步，你可以将应用发布到 Google Play 商店，或者在 Google Play 控制台上进行内部测试。 + +要进行内部测试，请运行以下命令： + +```bash +eas submit --platform android --profile staging +``` + +要公开发布你的应用，请运行以下命令： + +```bash +eas submit --platform android --profile production +``` + +更多关于构建配置文件的信息，请查看[这里](tutorial/publishing)。 + +恭喜你，到现在你已经完成了所有的步骤，你的移动应用现在已经上线，可以被用户下载了。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/publish-app.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/publish-app.md new file mode 100644 index 00000000..267f3e1a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/publish-app.md @@ -0,0 +1,11 @@ +--- +title: Publishing your App +--- + +:::danger Progress +This page has not been started yet or needs a lot more work. +::: + +Expo workflow, benefits of, etc. + +Over the air updates? diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/introduction.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/introduction.md new file mode 100644 index 00000000..f49c7ea8 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/introduction.md @@ -0,0 +1,8 @@ +--- +title: 简介 +slug: /push-notifications +--- + +Lexicon Discourse 插件为你的 Lexicon 手机应用提供了原生推送通知的支持。这适用于 Android 和 iOS，并由 Expo 的 [推送通知服务](https://docs.expo.dev/push-notifications/overview/)处理。 + +本文档提供了逐步说明，以便将推送通知无缝集成到你的 Discourse 站点中. 你的用户在 Lexicon 手机应用中接收到通知。遵循本指南，可以增强用户体验，确保他们及时接收到关于 Discourse 站点活动的通知。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/plugin-interaction.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/plugin-interaction.md new file mode 100644 index 00000000..f7fcd7ac --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/plugin-interaction.md @@ -0,0 +1,32 @@ +--- +title: 通知推送的原理 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + + +以下是关于通知推送在 Lexicon 移动应用程序中的实现，以及Prose 和 Discourse 插件之间的交互。 + +## Lexicon 移动应用 {#the-lexicon-mobile-app} + +Lexicon 移动应用在为用户启用推送通知方面发挥着至关重要的作用。当用户使用应用程序登录到他们的帐户时，使用 [`expo-notifications`](https://docs.expo.dev/versions/latest/sdk/notifications/) 库生成一个唯一的令牌。这个令牌作为用户设备的唯一标识符。然后，应用程序将此令牌发送到 Prose GraphQL API，后者会向 Lexicon Discourse 插件发出单独的请求。然后插件将记录插入到您的 Discourse 站点数据库中，确保 Discourse 上的任何相关活动都会触发推送通知到用户的移动设备。 + +## Prose {#prose} + +正如文档中的其他地方所提到的，Prose 是一个中间组件，它在 Lexicon 移动应用程序和您的 Discourse 站点之间进行通信。它发挥着提供 GraphQL 接口的关键作用，允许移动应用程序通过 GraphQL 与 Discourse 进行通信。 + +最新的 Prose API 暴露了一个新的 GraphQL mutation，`pushNotifications`，用于在用户登录时从移动应用程序接收唯一的 Expo 推送令牌。 + +Prose 从应用程序接收到令牌后会将其转发给运行在您站点上的 Discourse 插件。 + +## Discourse 插件 {#discourse-plugin} + +Lexicon Discourse 插件提供了几个功能。在启用推送通知方面，它负责与 Expo 的 [推送通知服务](https://docs.expo.dev/push-notifications/overview/) 集成。当 Discourse 插件从 Prose 接收到推送令牌时，它会将令牌保存在您的 Discourse 站点数据库中，并将其与相应的用户关联。 + +由于 Lexicon Discourse 插件已经配置为响应您的 Discourse 站点内的事件，因此它能够根据用户的活动发送推送通知。 + +当相关事件触发推送通知的需求时，例如新消息或回复时，Discourse 插件从您的 Discourse 站点数据库中检索与用户关联的令牌。使用此令牌，插件向 Expo 的推送通知服务发送推送通知请求，触发将推送通知发送到用户的设备。 + +## 交互流程 {#interaction-flow} + +Build Artifact diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md new file mode 100644 index 00000000..6a68a33e --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md @@ -0,0 +1,29 @@ +--- +title: 启用通知推送 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + + + + + + +我们将指导您完成为您的 Discourse 站点启用推送通知所需的步骤。 + +## 步骤 {#steps} + +1. 确保已安装并激活了[Lexicon Discourse 插件](../../discourse-plugin-installation.md)。 +2. 作为管理员用户，访问您的 Discourse 管理面板。 +3. 导航到插件部分。 + + + +4. 点击 `discourse-lexicon-plugin` 条目的 `设置` 按钮。 +5. 在 Lexicon 设置部分中选中 `启用推送通知` 复选框并保存更改。 + + + +启用了推送通知设置后，您的用户将能够通过移动应用程序登录并开始接收推送通知。 + +请注意，推送通知是在用户通过移动应用程序登录时专门设置的。如果用户没有收到推送通知，您应该指示他们退出并重新登录，然后再尝试进一步的故障排除。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md new file mode 100644 index 00000000..dac33c9b --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md @@ -0,0 +1,33 @@ +--- +title: 验证通知推送 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + + + + + +我们将指导您如何验证 Lexicon 手机应用中的推送通知功能。 + +:::info +为了正确测试推送通知，**您需要在您的 Discourse 站点上拥有两个不同的账户**（以生成通知）。 + +此外，**您需要至少一个移动设备**用于测试。 +::: + +## 步骤 {#step} + +为了在 Lexicon 手机应用中测试推送通知，请按照以下步骤操作： + +1. 确保您已完成 Lexicon 的[入门](../../quick-start)步骤。 +2. 通过在终端中导航到 `frontend/` 并运行 `yarn start` 来启动 Lexicon Expo 应用程序。 +3. 使用 Expo 链接或二维码，在真实移动设备上启动应用程序。 +4. 使用您的账户登录应用程序。 +5. 使用该账户在您的 Discourse 站点上创建一个帖子。 +6. 使用另一个账户回复帖子，以触发第一个账户的通知。 +7. 您应该在手机上收到一条推送通知，其中包含另一个账户的回复内容。 + + + +如果您收到了推送通知，恭喜！您已成功验证了 Lexicon 手机应用中的推送通知功能。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/quick-start.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/quick-start.md new file mode 100644 index 00000000..15d82c6c --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/quick-start.md @@ -0,0 +1,63 @@ +--- +title: 快速入门 +--- + +## 依赖 {#prerequisites} + +- Node.js 16.14 或更新版本 +- 与 Node 16.14 或更新版本兼容的最新版本的 NPM 或 Yarn +- EAS CLI 3.7.2 或更新版本，用于构建和发布应用 +- 一个可用的 Discourse 站点 + - 如果没有，请按照[开发配置](setup#discourse-host)中的说明操作 + +:::note +请按照[配置指南](tutorial/setup)中的说明安装依赖，例如 NPM 和 EAS CLI。 +::: + +## 安装 {#installation} + +首先，克隆本仓库并进入其中： + +``` +git clone git@github.com:lexiconhq/lexicon.git +cd lexicon +``` + +接下来，安装项目的依赖项并生成其 GraphQL schema： + +``` +$ npm install && npm run generate +``` + +`npm run generate` 包含两个步骤： + +- 首先，它将在 `api` 目录中生成一个 [GraphQL schema](https://nexusjs.org/docs/guides/schema)。 + +- 然后，使用生成的 schema，它将在 `frontend` 目录中创建一个名为 `generated` 的新文件夹，其中包含 the resulting query and mutation types。 这使得前端代码库可以与 `api` 目录中的类型保持同步，而无需重复编程。 + +从 API 共享的代码被 [Apollo](https://github.com/apollographql/apollo-tooling)(我们使用的前端 GraphQL 库) 使用, 使得移动应用可以正确地查询 API。 + +## 启动移动应用 {#launch-the-mobile-app} + +你可以通过从项目根目录运行以下命令来运行 Lexicon 移动应用并测试它： + +``` +$ npm run quickstart +``` + +这将同时启动两个进程： + +- Prose GraphQL API 服务器 +- 本地 Expo 开发服务器，使您可以从设备上启动 React Native 应用 + +**请注意，正确运行需要一些恰当的配置**。 + +- `quickstart` 命令配置了移动应用和 Prose GraphQL API，作为示例，使其指向 https://meta.discourse.org 。 + +- 您需要进行调整，以指向您选择的站点。 + +- Lexicon 移动应用（通过 Expo）必须配置为指向 Prose GraphQL 服务器 + +- Prose GraphQL 服务器必须配置为指向一个可用的 Discourse 站点 + +更多细节请参见[开发配置](setup)部分 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/rationale.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/rationale.md new file mode 100644 index 00000000..cef6c500 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/rationale.md @@ -0,0 +1,63 @@ +--- +title: 背景和愿景 +--- + +### Discourse在移动端体验的策略 {#discourses-approach-to-a-mobile-experience} + +Discourse是一款非常出色、被广泛使用的论坛，在全球无数基于此的中社区产出了大量有价值的讨论。当然，我们也是Discourse的超级粉丝。 + +Discourse核心团队在移动设备上的策略是将他们的产品实现为响应式网站，并针对移动使用场景进行优化。这使得移动用户可以直接访问与大屏设备上相同的Discourse网站，从而能够在移动设备上查看和发布帖子。 + +然而，随着时间的推移，对于专门的Discourse移动应用的需求越来越大。核心团队通过构建一个原生移动应用来满足这一需求。他们选择重用现有的工作，让应用程序简单地包装一个包含移动站点的Web视图。 + +这是一个很好的改进，因为它使移动应用能够与原生SDK集成，并为Discourse移动用户提供一些额外的功能。 + +总体而言，他们解决这个问题的方法既高效又出色。 + +然而，对于许多用户来说，他们仍然明显地感觉到在与一个嵌入式的Web浏览器进行交互，很明显这不是一个以移动端为先的体验。 + +对于许多用户和站点所有者来说，Discourse 团队提供的已经足够解决他们的所有问题。 + +但是对我们来说，我们在探索一种特殊的体验方式。 + +### 我们是谁 {#who-we-are} + +Lexicon 团队是[KodeFox](https://www.kodefox.com/)的一部分，KodeFox是一个由充满激情的软件工程师、设计师和产品经理组成的软件工作室，时常为我们的客户构建世界一流的软件。 + +如果对个人化的定制软件开发感兴趣，通过邮件联系我们：[hello@kodefox.com](mailto:hello@kodefox.com)。 + +### 进入Lexicon {#enter-lexicon} + +Lexicon 的源于分享 Discourse 团队辛勤工作所建立的许多出色功能的愿望。 + +在我们的咨询项目中，我们发现许多客户经常需要 Discourse 已经提供了的解决方案。但是，我们的客户希望一个无缝的、与他们的用户已经熟悉的品牌相适应的原生移动体验。 + +在深入研究 Discourse API 文档后，我们认为构建一个以移动为先的Discourse体验并促进可定制性是值得投资的。 + +我们已经熟悉 React Native 和 Expo 提供的优雅开发流程，所以它非常适合我们使用这些技术构建移动应用。这使我们能够在iOS和Android之间实现高比例的代码重用，使特性实现和错误修复在大多数情况下变得更加简单。 + +在与 Discourse 的 API 集成中，我们还注意到 API 文档包含一个鼓励通过逆向工程来理解它的免责声明。尽管我们可以理解自己摸索事物的情感，但我们希望提供一种使开发人员能够深入了解交互式文档并快速掌握概念的 API 体验。 + +因此，我们选择在 Discourse RESTful API 之上的 GraphQL API 层构建了我们的 Prose。另一个推动因素是我们对 GraphQL 相当熟悉，这使我们能够快速使用直观的API范例来实现移动应用。 + +#### Lexicon如何帮助您 {#how-lexicon-can-help-you} + +如果您正在维护现有的Discourse站点，并希望为您的用户提供原生移动体验，您可以很快地将 Lexicon 指向您的站点，并从您的设备实时浏览它。 + +查看[快速入门](quick-start)页面，了解如何为 Discourse 的[Meta站点](https://meta.discourse.org)快速创建一个移动应用的示例。 + +除此之外，Lexicon 是一个开源的预构建移动应用。这意味着您可以根据自己的品牌进行定制。您可以将其视为一个模板，用于为您的社区构建自己的移动应用。如果您有兴趣定制Lexicon移动应用，您可以在[白标](white-labeling)部分了解更多信息。 + +完成后，您可以将其发布到 Apple App Store 或 Google Play Store，我们在[发布您的应用](app-store)中介绍了这一过程。 + +### FOSS Mindset - 开源理念 {#foss-mindset} + +> 译者注: FOSS即 Free & Open Source Software，自由开源软件. + +最后，尽管这个项目将为我们和我们的客户带来很多好处，同时我们也希望它成为给开发社区的一份礼物。 + +我们了解并支持自由开源软件的文化，这就是为什么我们很高兴以这种方式回馈社区，就像Discourse团队最初选择开源他们的辛勤工作一样。 + +因此，请在Github上与我们互动，不要害羞，可以提出新问题或者提交PR。 + +我们期待与您合作！ diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/setup.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/setup.md new file mode 100644 index 00000000..f601b57a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/setup.md @@ -0,0 +1,377 @@ +--- +title: 开发配置 +--- + +### 克隆 Lexicon 仓库 {#clone-the-lexicon-repository} + +若尚未完成此步，请确保从 Github [克隆 Lexicon 仓库](quick-start#installation)。 + +### 配置 Discourse 实例（如果需要） {#setup-a-discourse-instance-if-necessary} + +你需要一个正在运行的 Discourse 站点才能开始开发 Lexicon Stack。 + +顺便回顾一下，Lexicon Stack 由以下组成： + +- Lexicon App +- The Lexicon Prose GraphQL API +- 一个可用的 Discourse 站点 + +没有 Discourse 站点，Prose GraphQL API 就无法获取数据。而当 Prose GraphQL API 无法获取任何数据时，Lexicon 移动应用程序也无法接收任何数据。 + +有关设置本地开发实例的详细说明，请转到 [教程](./tutorial/setup-discourse)，该教程将引导您完成整个过程。 + +但是，如果您已经部署了 Discourse 站点，我们建议使用该它。 + +### 安装 Lexicon Discourse 插件 {#install-the-lexicon-discourse-plugin} + +Lexicon Discourse 插件是一个 Discourse 插件，它为 [推送通知](./push-notifications/introduction.md) 和 [电子邮件深度链接](./email-deep-linking/intro.md) 提供支持。 + +您可以按照 [Discourse 插件文档](./discourse-plugin.md) 中的说明在您的 Discourse 实例中安装插件。 + +对于本地开发，您只能测试推送通知，因为电子邮件深度链接需要具有 [有效 app scheme](https://docs.expo.dev/versions/latest/config/app/#scheme) 的已发布应用程序。 + +如果您希望针对插件本身进行开发，可以在[此处](https://github.com/lexiconhq/discourse-lexicon-plugin.git)获取源码。 + +### 配置 {#configuration} + +Lexicon Stack 的配置需要一些工作，以便与您的 Discourse 服务器正确交互。 + +这涉及配置后端 GraphQL API，该 API 与您的 Discourse 站点交互；以及前端移动应用程序，该应用程序与 GraphQL API 交互。 + +此设置的架构在 [Lexicon Stack 架构](concepts#architecture-of-the-lexicon-stack) 中有所描述。 + +#### 后端 GraphQL API 配置 {#backend-graphql-api-configuration} + +[Prose GraphQL API](concepts#prose-discourse-through-graphql) 在配置方面相当简单。在最简单的情况下，它只需要知道您的 Discourse 站点在哪里可以访问。 + +它通过 `api/` 目录中的根目录中的 [`.env` 文件](https://www.codementor.io/@parthibakumarmurugesan/what-is-env-how-to-set-up-and-run-a-env-file-in-node-1pnyxw9yxj) 接收其配置。 + +以下是 `api/.env` 文件的最简单配置： + +``` +PROSE_DISCOURSE_HOST=https://meta.discourse.org +``` + +值得注意的是，您还可以选择配置 Prose API 服务器监听的 **主机名** 和 **端口号**，它们的默认值分别为 **localhost** 和 **80**。 + +``` +PROSE_DISCOURSE_HOST=https://meta.discourse.org + +# Instruct Prose to broadcast publicly instead of on localhost +PROSE_APP_HOSTNAME=0.0.0.0 + +# Instruct Prose to listen on port 8929 instead of the default port 80 +PROSE_APP_PORT=8929 +``` + +这些[Prose 环境变量](env-prose)是可选的，但是在某些情况下可能会很有用。 + +#### 前端移动应用程序配置 {#frontend-mobile-app-configuration} + +:::note +在最初的 Lexicon 中，**Prose URL** 是在 `frontend/.env` 中指定的。但是，作为迁移到 Expo 的 EAS 功能的一部分，我们将配置集中到 `frontend/Config.ts` 中，以省去您在多个地方维护它的麻烦，正如[Expo 文档](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update)中建议的那样。 +::: + +你需要先在 `frontend/app.json` 中设置你的应用名称和 slug 来配置移动 APP。[slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) 也被用作 Expo Web 服务上应用程序的 URL 的一部分，因此建议使用 kebab-case（例如，`my-lexicon-app`）。 + +请注意，这些占位符是您的应用程序的名称和 slug，您需要将它们替换为您想要的值： + +```json + "name": "", + "slug": "", +``` + +接下来，将 `frontend/Config.ts` 中的 `proseUrl` 的值更改为您的 Prose GraphQL API 的 URL，无论是本地还是已经部署在某个地方。 + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com:8080/subpath', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +`localDevelopment.proseUrl` 会在您使用 `npm run start` 或 `expo start` 运行应用程序进行开发时被使用，而在实际构建应用程序时将使用 `buildChannels` 中的特定值（例如，`production.proseUrl`）。 + +#### 开发场景 {#development-scenarios} + +在本地开发时，您可能会发现自己处于至少三种不同的场景中。 + +根据您所处的场景，`frontend/Config.ts` 和 `api/.env` 可能需要不同的配置。 + +##### 场景 1：现有 Prose 部署 {#scenario-1-existing-prose-deployment} + +如果您已经将 Prose GraphQL API 部署到可以公开访问的主机上，您将已经使用正确的值设置了 `api/.env`。 + +在此情况下，`frontend/Config.ts` 只需要更新以指向已部署的 GraphQL API。 + +例如： + +```ts +const config = { + localDevelopment: { + proseUrl: 'https://my-deployed-graphql.api', + }, + buildChannels: { + preview: { + proseUrl: 'https://my-deployed-graphql.api', + }, + production: { + proseUrl: 'https://my-deployed-graphql.api', + }, + }, +}; +``` + +在上面的示例中，我们已经配置了应用程序在所有情况下都指向 `https://my-deployed-graphql.api`，包括在使用 `npm run start` 运行时。 + +##### 场景 2：本地运行 Prose 并从模拟器访问 {#scenario-2-run-prose-locally--access-from-a-simulator} + +:::info +如果您在本地运行 Prose 服务器，只有在部署了 Prose 的开发设备在运行状态时 Lexicon 才能正常工作。如果你需要在不依赖于开发设备的情况下使用移动应用程序之前，您必须先**部署** Prose 服务器。 +::: + +这种方法包含在开发机器上同时运行 Lexicon 移动应用程序和 Prose GraphQL API。这是通过指示 Expo 在 Android 或 iOS 模拟器中启动移动应用程序来实现的。 + +当以这种方式进行开发时，您可以简单地将 `frontend/Config.ts` 中的 `localDevelopment.proseUrl` 设置为 `http://localhost`。然后在 `api/.env` 中，您可以将 `PROSE_APP_HOSTNAME` 设置为 `0.0.0.0`。 + +请注意，如果您希望在特定端口上本地运行 Prose，您需要确保 `api/.env` 和 `frontend/Config.ts` 中的配置正确反映了这一点。 + +:::caution +如果您在 `api/.env` 中配置 `PROSE_APP_HOSTNAME` 仅监听 `localhost` 或 `127.0.0.1`（而不是 `0.0.0.0`），则会阻止同一网络上的其他人访问它。这包括您的移动设备和 Android 模拟器，这可能会导致在本地开发时出现连接问题。 +::: + +##### 场景 3：在本地运行 Prose 并从移动设备访问 {#scenario-3-run-prose-locally--access-from-your-mobile-device} + +使用真实移动设备上的应用程序进行开发和调试非常有用，您可以使用 [Expo Go 应用程序](https://expo.dev/client)在真实的移动设备上开发和调试应用程序。 + +为了实现这一点，您需要确保您的开发设备是可以从移动设备上访问得到的。 + +使其可访问的一个简单方法是确保您的移动设备和开发设备连接在同一网络上，然后在 `api/.env` 中，将 `PROSE_APP_HOSTNAME` 设置为 `0.0.0.0`。 + +在常规的 Expo 项目中，您需要更新 `frontend/Config.ts` 中的 `localDevelopment.proseUrl` 值，以硬编码的方式配置您的开发设备在网络上的 IP 地址。 + +然而，通过将值设置为 `http://localhost`，我们默认情况下**自动**处理这一点，因此您无需担心。[这里](env-mobile#infer_development_host)有更多信息。 + +##### 硬编码本地 IP 地址 {#hardcoding-your-local-ip-address} + +:::info +这种方式并不理想。如果您的本地 IP 地址发生变化，您将需要重新查找它，并更新 `Config.ts` 以反映这一点。因此，最好只使用 `http://localhost`。 +::: + +要手动指示移动应用程序如何定位您的开发设备，您需要找出您的开发设备在当前网络上的 **本地 IP 地址**。 + +请注意，您的本地 IP 地址与您的公共 IP 地址不同。 + +如果您不确定如何获取本地 IP 地址，您可以转到 [What Is My Browser: Detect Local IP Address](https://www.whatismybrowser.com/detect/what-is-my-local-ip-address) 并按照说明操作。 + +网站本身可能无法自动检测到您的本地 IP 地址，但它将为您提供有关如何在特定操作系统中找到它的说明。 + +您将获得一个类似 `10.0.12.121` 或 `192.168.17.69` 的 IP 地址。 + +然后，您可以将 `frontend/Config.ts` 中的值更新为您的本地 IP 地址。 + +这将允许在您的移动设备上运行的应用程序正确定位在您的开发设备上运行的 GraphQL API。 + +## 配置您的 Discourse 站点 {#configure-your-discourse-host} + +如上所述，您需要设置一个 Discourse 站点，以便 GraphQL API 与之交互。 + +我们想简要介绍一下在继续之前设置 Discourse 主机的不同方法。 + +**1. 本地运行 Discourse 实例** + +:::note +请确保正确管理所有端口。 + +Discourse 的开发设置使用 Docker，其中使用了多个端口，其中之一是 **端口 3000**。您需要仔细检查没有其他的环境变量占用 Discourse 要使用的端口。 +::: + +如果您想在本地运行 Discourse 站点进行开发，建议使用 **[Docker](https://www.docker.com/)**，因此请确保已安装它。 + +然后，如上所述，您可以按照 [教程中的这些步骤](tutorial/setup-discourse) 在 Docker 中安装和运行 Discourse 的开发实例。 + +**2. 使用 try.discourse.org 或其他流行的 Discourse 站点** + +:::info +可以随意使用现有的公共 Discourse 站点，例如 [Docker Community Forum](https://forums.docker.com/) 或 [Rust Programming Language Forum](https://users.rust-lang.org/)，以测试 Lexicon 移动应用程序。 + +只需注意您如何在这些站点上进行贡献即可。 +::: + +[Try Discourse](https://try.discourse.org/) 是一个公开可访问的 Discourse 站点，旨在用于测试。因此，它每天都会重置。 + +您可以在这里注册一个新用户，然后在 Lexicon 移动应用程序中使用登录凭据。 + +使用这种方法，您只需在 `api/.env` 中配置 Prose 指向这些实例之一的主机。 + +```bash +PROSE_DISCOURSE_HOST=https://try.discourse.org +``` + +## 准备开发环境 {#prepare-the-development-environment} + +现在您已经为开发做好了准备，可以开始深入了解 Lexicon 代码库。 + +### 运行 Lexicon 移动应用程序和 Prose GraphQL 服务器 {#run-the-lexicon-mobile-app--prose-graphql-server} + +您可以通过运行以下命令 **从项目根目录** 运行移动应用程序并使用本地 Prose 服务器进行测试： + +``` +$ npm run dev +``` + +这会同时启动两个进程： + +- GraphQL API 服务器 +- 本地 Expo 开发服务器，它将使您能够从设备启动 React Native 应用程序 + +但是，如果您希望分别运行前端和后端，请在终端中执行以下命令以运行前端： + +``` +$ npm run --prefix frontend start +``` + +然后在另一个终端中执行以下命令以运行后端： + +``` +$ npm run --prefix api dev +``` + +### 调试 {#debugging} + +- 使用 [Expo Developer Menu](https://docs.expo.io/workflow/debugging/#developer-menu) 可以使调试过程更容易。 + +根据不同的设备选择合适的方式打开 Expo Developer Menu： + +- 在 iOS 设备上：摇动设备，或者用 3 个手指触摸屏幕。 +- 在 iOS 模拟器上：在模拟器中按 `⌘ + ctrl + Z`。 +- 在 Android 设备上：垂直摇动设备，或者在终端窗口中运行 `adb shell input keyevent 82`。 +- 在 Android 模拟器上：按 `⌘ + M`，或者在终端窗口中运行 `adb shell input keyevent 82`。 + +- 如果您的更改没有显示出来，可能与缓存有关。在这种情况下，您应该尝试重新启动 Expo。 + - 为此，请在运行的终端中按 `Ctrl + C` 退出进程。 + - 然后再次运行 `npm run start`。 + - 如果问题仍然存在，您应该查找 Expo 的最新指导，因为它已知会发生变化。 + +### 运行测试套件 {#running-the-test-suites} + +在运行测试之前，请仔细检查您的更改是否不包含任何错误。 + +您可以通过从项目根目录运行以下命令依次运行前端和后端代码库中的测试： + +``` +$ npm run test +``` + +确保所有测试都已通过，该命令还会通知您是否存在任何 Typescript 错误或来自 Prettier 或 ESLint 的问题。 + +还要注意，在运行 `npm run test` 之前，会触发前端中的另一个操作。 + +一个新的文件夹 `frontend/generated` 将被创建，并填充所有 GraphQL Query 和 Mutation types，以供代码库使用。 + +如果我们在测试之前没有运行这个，由于类型错误，测试会失败。 + +### 构建和发布 Lexicon 移动应用程序 {#build--publish-the-lexicon-mobile-app} + +:::note +要想使用 Expo 的服务，您需要一个 Expo 账户。您可以在这里创建一个：https://expo.io/signup。 +一旦您创建了 Expo 账户，请确保您已经在当前 shell 会话中登录了您的 Expo 账户，通过 `expo login` 或 `eas login`。 +::: + +在构建 Lexicon 移动应用程序之前，您需要先通过运行以下命令配置 EAS 构建： + +```bash +eas build:configure +``` + +然后，您将从 EAS CLI 得到与 EAS 项目 ID 相关的提示：`android.package` 和 `ios.bundleIdentifier`。如果您有一个现有的项目 ID，EAS 将为您提供一个现有的项目 ID，否则会要求您创建一个新的项目 ID。至于 `android.package` 和 `ios.bundleIdentifier`，您可以使用 `com.companyname.appname` 或您可能更喜欢的任何其他模式来指定这些值。 + +完成后，请验证您将在 `Config.ts` 中用于实际构建应用程序的 `proseUrl` 值。 + +:::info +在发布应用程序时，有必要将 Prose 部署在某个公开可访问的地方，例如在 AWS 或 DigitalOcean 这样的云托管提供商上。如果 Prose 仅在您的本地机器上运行，那么下载您的应用程序的用户将无法使用它。 +如果你尚未部署 Prose，请查看[文档](deployment)。 +::: + +现在，您可以通过 Expo（EAS）使用预览构建配置文件构建移动应用程序，运行以下命令： + +```bash +eas build –platform all –profile preview +``` + +当您这样做时，打包程序将会压缩所有代码并生成两个版本的代码——一个用于 iOS，一个用于 Android——然后将它们都上传到 Expo CDN。 + +此外，如果您尚未优化应用程序的资产，Expo 将询问您是否要这样做。 + +这与手动运行 `npx expo-optimize` 具有相同的效果。它只是压缩项目中的所有图像资产，以减小构建的大小。 + +完成后，您将看到一个可共享的二维码和一个类似于 https:xxxxx.xxxxx@xxxxxxxxxxxxxxxxxxx 的 URL，该 URL 将您引导到 Expo 的 Web 控制台中的构建详细信息。 + +此时，任何人都可以使用该链接加载您的项目。 + +对于 Android，您可以将应用程序安装在模拟器或物理设备上。但是，对于 iOS，您只能将其安装在 iOS 模拟器上。要在真实的 iOS 设备上运行应用程序，请按照[教程](tutorial/building#1-preview)中的步骤。 + +在构建应用程序时，建议首先构建预览构建，并确保一切正常运行，然后再使用生产配置文件构建发布。 + +要使用生产构建配置文件构建应用程序，请运行以下命令： + +```bash +eas build –platform all –profile production +``` + +完成后，您将看到与预览构建相同的输出。您还将看到指向 Expo 中构建详细信息的链接。 + +但是，与预览构建不同，发布构建不会生成一个可安装的二进制文件。您需要发布应用程序，然后从 Play Store 或 App Store 安装它。 + +您可以在[教程](tutorial/building)的这一部分中阅读更详细的解释。 + +#### 更新 {#updates} + +如果您稍后想要部署 Lexicon 移动应用程序的更新，您可以使用 EAS 更新命令。 + +首先，请确保通过运行以下命令配置 EAS 更新： + +```bash +eas update:configure +``` + +此命令将自动向您的 `app.json` 文件添加 `expo.runtimeVersion` 字段。 +您将在终端中看到一个警告，告诉您要将 `expo.updates.url` 添加到 `app.json`。 + +然后运行以下命令来更新您的项目： + +```bash +eas update -–branch +``` + +:::note +channel 名称与构建配置文件相同，因此对于预览构建，您可以运行： + +```bash +eas update -–branch preview +``` + +::: + +有关更新应用程序的更多信息，请在[此处](tutorial/updating)阅读。 + +新版本发布后，下次用户打开应用程序时，新版本将对他们可用。 + +更多有关此过程的详细信息，包括发布到 App Store 和 Google Play Store，请按照[发布您的应用程序](tutorial/publishing)中的说明。 + +#### 配置 GraphQL API 与您的 Discourse 服务器 {#configure-the-graphql-api-with-your-discourse-server} + +为了发布版本的应用程序能够联系您的 Discourse 服务器，您需要确保： + +- GraphQL API 已部署并在从应用程序本身可访问的主机上运行正常 +- GraphQL API 已配置为指向您的 Discourse 服务器的正确主机和端口 +- 您的 Discourse 服务器可以通过 GraphQL API 访问 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/supported-devices.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/supported-devices.md new file mode 100644 index 00000000..97bd9cf7 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/supported-devices.md @@ -0,0 +1,31 @@ +--- +title: 兼容设备 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## iPhone 和 Android 手机 {#iphone-and-android-phones} + +:::info +旧版本的 iOS and Android 也许可以正常运行, 但是并不受官方支持. +::: + +你在 App Store 或 Google Play Store 上发布了应用程序后，你的已发布应用程序将在 iPhone 和 Android 设备上为用户提供开箱即用的功能，具体系统要求如下： + +| 设备 | 最低系统版本 | +| --------------- | -------------------- | +| iPhone | iOS 16 或更高 | +| 安卓设备 | Android 13 或更高 | + +| 安卓 | iOS | +| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| | | +| | | +| | | +| | | + +## 其他设备的兼容性 {#support-for-other-devices} + +到目前为止, **大屏设备（包括iPad）**和其他移动端设备**并不兼容** Lexicon.我们未来也许会提供对这些设备的兼容. + +如果这真的对你非常重要, 请通过邮件 support@kodefox.io 告知我们. diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/technologies.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/technologies.md new file mode 100644 index 00000000..7c692e9f --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/technologies.md @@ -0,0 +1,21 @@ +--- +title: 技术路线 +--- + +### 100% 使用 React Native 和 TypeScript 在 Expo 构建 {#100-react-native-and-typescript-built-on-expo} + +Lexicon 是使用单一代码库构建和维护的，这意味着大部分情况下的 bug 修复、改进和新功能都会自动应用于 iOS 和 Android。 + +### 基于 GraphQL 的 API {#graphql-based-api} + +希望为 Lexicon 提交贡献或者二次开发的开发者也可以利用好 GraphQL 的所有优势。更多信息请查看[概念和架构](concepts#prose-discourse-through-graphql)。 + +### 白标支持 {#white-labeling-support} + +通过白标功能，您可以使 Lexicon 移动应用程序具有您品牌的熟悉外观和体验。了解更多信息请参阅[白标](white-labeling)。 + +### 与现有 Discourse 站点轻松集成 {#painless-integration-with-existing-discourse-instances} + +只需为 Prose GraphQL API 启动一个新服务器，并将其指向您的 Discourse 站点，即可轻松入门。您的 Discourse 站点本身不需要进行任何更改。 + +注意：要启用诸如[推送通知](./push-notifications)和[电子邮件深度链接](./email-deep-linking/intro.md)等功能，您可以安装我们的[Discourse 插件](./discourse-plugin.md)。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/theming.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/theming.md new file mode 100644 index 00000000..a0d3a6d7 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/theming.md @@ -0,0 +1,247 @@ +--- +title: 主题 +--- + +:::note +本节将涉及阅读和修改 Typescript。如果遇到困难，请联系我们。 +::: + +Lexicon 允许您自定义移动应用程序提供的默认主题。 + +你可以通过修改`frontend/src/constants/theme` 或 `frontend/src/theme` 中的参数来实现这一点。 + +这两者之间有所不同，并且它们相互配合使用。 + +`frontend/src/constants/theme` 定义了主题的基础值。 + +然后`frontend/src/theme` 导入这些值，并使用它们来组合实际的主题对象，该对象在移动应用程序的其余部分中使用。 + +## 颜色 {#colors} + +### 调整基础和功能颜色 {#adjusting-base--functional-colors} + +移动应用程序中有两种类型的颜色：基础颜色和功能颜色。 + +基础颜色是主题的基本调色板，而功能颜色定义了基础颜色的特定用例。 + +例如，您可能已经注意到移动应用程序使用漂亮而引人注目的皇家蓝作为其主要颜色。 + +这在基础颜色中定义为： + +```ts +// ... +royalBlue: '#2B6AFF', +// ... +``` + +然后，功能颜色利用这一点来为应用程序中的特定组件提供颜色。 + +继续看这个例子，`royalBlue` 基础颜色在功能颜色中被引用为： + +```ts +// ... +activeTab: BASE_COLORS.royalBlue, +// ... +primary: BASE_COLORS.royalBlue, +// ... +``` + +现在，任何组件都可以引用功能颜色的 `primary` 值，它将是 `royalBlue`。 + +当然，如果您想要一个不同主题的新颜色，例如 `BASE_COLORS.lightningYellow`，那么您可以调整为： + +```ts +// ... +activeTab: BASE_COLORS.lightningYellow, +// ... +primary: BASE_COLORS.lightningYellow, +// ... +``` + +然后移动应用程序将用您为亮黄色定义的值替换皇家蓝。 + +因此，如果您想添加更多颜色，您需要首先添加基础颜色值，然后在功能颜色中访问它们。 + +这种方式保持了关注点的清晰分离，使主题更改能够无缝传播到移动应用程序中。 + +### 调整颜色方案（暗色模式和亮色模式） {#color-scheme-dark-mode-and-light-mode} + +主题允许您控制用户如何调整应用程序的颜色方案，如果有的话。 + +这有三种选择：暗色 `dark`、亮色 `light`、无偏好（默认） `no-preference`。 + +- 暗色：强制颜色方案保持暗色 +- 亮色：强制颜色方案保持亮色 +- 无偏好（默认）：允许用户指定颜色方案的偏好 + +注意，如果您指定了 `dark` 或 `light`，您的用户将**没有**选择颜色方案偏好的选项。 + +这在移动应用程序中体现为隐藏通常出现在首选项场景中的暗色模式按钮。 + +## 字体 {#fonts} + +主题的字体在 `frontend/src/constants/theme/fonts` 中定义。 + +在该文件中，您可以找到调整的字体的多个属性： + +- 字体变体 +- 字体大小 +- 标题字体大小 + +### 字体变体 {#font-variants} + +用于为变体配置字重。它支持以下值： + +| Variants | Default font weight | +| -------- | ------------------- | +| 粗体 | 700 | +| 半粗体 | 600 | +| 正常 | 400 | + +### 字体大小 {#font-sizes} + +用于设置整个应用程序中一致的字体大小。它支持以下值： + +| Variants | Default size | +| ---------------- | ------------ | +| xl (extra large) | 24 | +| l (large) | 18 | +| m (medium) | 16 | +| s (small) | 14 | +| xs (extra small) | 12 | + +### 标题字体大小 {#heading-font-sizes} + +用于为标题元素（如 `h1`、`h2` 等）配置字体大小。 + +这些值主要用于呈现来自 Discourse 的帖子和消息的内容。 + +这是因为 Discourse 帖子是用 Markdown 编写的，用户通常会利用标题元素来格式化他们的帖子。 + +| Variants | Default size | +| -------------- | ------------ | +| h1 (Heading 1) | 32 | +| h2 (Heading 2) | 24 | +| h3 (Heading 3) | 22 | +| h4 (Heading 4) | 20 | +| h5 (Heading 5) | 18 | +| h6 (Heading 6) | 17 | + +## 图标 {#icons} + +`icons` 主题文件用于存储与图标相关的常量。 + +目前，`icons` 文件仅包含一个常量，它声明了图标大小的比例。 + +| Variants | Default size | +| ---------------- | ------------ | +| xl (extra large) | 28 | +| l (large) | 24 | +| m (medium) | 20 | +| s (small) | 18 | +| xs (extra small) | 16 | + +## 图像 {#images} + +`images` 主题文件用于存储在渲染图像中使用的主题常量。 + +目前，该文件声明以下主题值： + +- Avatar 图标大小 +- Avatar 字母大小 +- Avatar 图像大小 + +Avatar 在整个应用程序中用于显示有关帖子或消息的相关信息。 + +一般来说，它通常是用户自定义的头像。 + +然而，当没有提供头像时，我们还会根据用户的首字母生成一个基于字母的头像。 + +### Avatar 图标大小 {#avatar-icon-size} + +| Variants | Default size | +| ---------------- | ------------ | +| l (large) | 96 | +| m (medium) | 52 | +| s (small) | 40 | +| xs (extra small) | 28 | + +### Avatar 字母大小 {#avatar-letter-size} + +| Variants | Default size | +| ---------------- | ------------ | +| l (large) | 72 | +| m (medium) | 36 | +| s (small) | 28 | +| xs (extra small) | 16 | + +### Avatar 图像大小 {#avatar-image-size} + +This defines the quality of the image used for avatars. + +| Variants | Default size | +| ---------------- | ------------ | +| xl (extra large) | 450 | +| l (large) | 150 | +| m (medium) | 100 | +| s (small) | 50 | + +## 间距 {#spacing} + +`spacing` 主题文件定义了在移动应用程序中用于填充和边距的间距常量。 + +| Variants | Default size | +| ------------------------- | ------------ | +| xxxl (triple extra large) | 36 | +| xxl (double extra large) | 24 | +| xl (extra large) | 16 | +| l (large) | 12 | +| m (medium) | 8 | +| s (small) | 4 | +| xs (extra small) | 2 | + +## 高级自定义 {#advanced-customization} + +虽然上述调整通常相当简单，但您可以根据自己的技能水平真正自定义移动应用程序（基于您的技能水平）。 + +以下是一些额外的示例。 + +### 自定义字体 {#custom-fonts} + +#### 创建一个用于自定义字体的文件夹 {#create-a-folder-for-the-custom-fonts} + +为了保持代码库的结构，您可以在 `frontend/assets` 中创建一个名为 `fonts` 的文件夹。 + +然后，您可以将自定义字体资源移动到此文件夹中。 + +#### 安装并使用 `expo-font` 包 {#install--use-the-expo-font-package} + +这个包简化了将自定义字体添加到基于 Expo 的应用程序的过程。 + +特别是，您将使用其中的 `loadAsync` 函数，该函数将您的字体资源映射到移动应用程序中的变体名称。 + +虽然我们不会在这里详细介绍太多技术细节，但他们的[文档](https://docs.expo.dev/versions/latest/sdk/font/)可以指导您完成这个过程。 + +### 错误消息 {#error-messages} + +在移动应用程序中，错误消息是用户与应用程序交互时的重要部分。 + +为了更改或添加新的错误消息，您需要了解两个文件。 + +#### `frontend/src/helpers/errorMessage.ts` {#frontendsrchelperserrormessagets} + +Prose GraphQL API 会将来自 Discourse 的错误消息转发。 + +此文件将这些消息的具体文本声明为常量，以便可以轻松地在 `errorHandler.ts` 中进行比较。 + +如果您观察到任何未被捕获的额外错误消息，您需要将它们添加到此文件中，然后相应地调整下面的 `errorHandler.ts`。 + +#### `frontend/src/helpers/errorHandler.ts` {#frontendsrchelperserrorhandlerts} + +此文件从上面的 `errorMessage.ts` 导入。 + +然后，当遇到错误时，它定义了如何处理错误，包括上面的消息。 + +目前，默认方法是向用户显示错误消息。 + +但是，如果您想集成 snackbar，您需要调整 `errorHandler.ts` 中的代码，以替换 `Alert.alert` 的调用。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/troubleshooting-build.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/troubleshooting-build.md new file mode 100644 index 00000000..34a34d40 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/troubleshooting-build.md @@ -0,0 +1,128 @@ +--- +title: 异常排查 +--- + + + + + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## 无法连接到 URL 的连接和配置问题 {#troubleshooting-connection-and-configuration-issues-with-url} + +
+ please connect to network error +
+ +如果您遇到与 URL 相关的问题，导致错误消息显示“请连接到网络”，如屏幕截图所示，很可能是由于配置不正确引起的。具体而言，如果您正在尝试在移动设备上本地测试构建，并且 channel 字段未正确配置，则应用可能会持续回退到 localDevelopment 频道，即使您已将其设置为其他频道，如“preview”。 + +以下步骤和注意事项可帮助解决此问题： + +- 打开项目中的 `frontend/Config.ts` 文件。 +- 在文件中查找 `config` 对象。 +- 在 `localDevelopment` 部分的 `config` 对象中，您可以添加特定于您要测试的频道的 Prose URL。此部分用于本地开发，并作为 EAS Build 中未知构建频道的默认配置。以下是一个示例： + + ```ts + const config: Config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, + }; + ``` + +- 上面的示例显示了配置由两个主要部分组成：`localDevelopment`，它指定了本地开发期间的 URL，以及 `buildChannels`，其中包括不同频道的配置，如 preview 和 production。对于本地开发，它将使用 URL `http://localhost:8929` 访问 Prose API。如果构建频道未知或未找到，则始终会默认为 localDevelopment。 +- 使用有效的 Prose 服务器 URL 为特定的构建更新 `proseUrl` 值，例如 `preview` 或 `production` 中的值。 +- 进行了必要的更改之后，请保存 `frontend/Config.ts` 文件。 + +现在，当您为特定的构建频道运行 `eas build`，例如 `eas build --profile=production` 时，它将使用生产配置中指定的 Prose URL。 + +:::note +在 `frontend/app.json` 中包含 URL 是很重要的，expo-updates 将使用它来获取更新清单。如果未在 `frontend/app.json` 文件中设置 URL，expo-updates 将始终返回 undefined 作为频道的常量，导致应用在构建后始终使用 localDevelopment URL。您可以在 app.json 文件的 expo 和 updates 部分中指定此 URL。有关如何配置此项的更详细信息，请参考[expo 文档](https://docs.expo.dev/versions/latest/config/app/#url)。 + +```json +"expo": { + "updates": { + ..., + "url": "https://u.expo.dev/" + } +} +``` + +这种配置对于与项目中的 Config.ts 无缝集成至关重要。 +::: + +在某些情况下，当 `frontend/eas.json` 文件中指定的 channel 名称与 `frontend/Config.ts` 文件中定义的 `config` 变量中的相应键名不匹配时，可能会遇到与 Prose API URL 相关的问题。这种不一致可能会导致问题，因为 `eas.json` 中的 channel 名称用于确定将要使用的 URL。如果名称不匹配，则将使用默认的 `localDevelopment` URL。 + +为了确保顺利运行，请注意在 `frontend/eas.json` 文件和 `frontend/Config.ts` 文件中使用相同的 channel 名称。这将确保将 channel 名称正确映射到相应的 URL。 + +以下示例可帮助说明这一点： + +```json +// frontend/eas.json + +"build": { + "staging": { + "android": { + "buildType": "apk" + }, + "channel": "staging" + } +} +``` + +```ts +// frontend/Config.ts; + +const config: Config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + inferDevelopmentHost: true, + }, + + buildChannels: { + preview: { + proseUrl: '', + }, + production: { + proseUrl: '', + }, + staging: { + proseUrl: '', + }, + }, +}; +``` + +## 应用闪退 {#the-app-closes-abruptly-after-the-splash-screen} + +如果应用在启动时闪退，很可能是您的 `app.json` 文件中缺少配置引起的。一个常见的原因是在 `app.json` 中缺少 scheme 定义，这在应用构建过程中是必不可少的。 + +参照下述步骤解决此问题： + +1. 打开项目的 `frontend/app.json` 文件。 +2. 查找 `"expo"` 部分。 +3. 如果 scheme 不存在，请在 `"expo"` 部分中添加以内容： + + ```json + "expo":{ + "name": "", + "slug": "", + "scheme": "", + "version": "1.0.0" + } + ``` + + 将 `""` 替换为您的应用程序的所需 scheme 名称。 + +4. 保存对 `app.json` 文件的更改。 +5. 重新构建您的应用程序并再次测试。 + +在 `app.json` 中正确定义 scheme 后，您应该能够解决应用在启动时闪退的问题。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/building.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/building.md new file mode 100644 index 00000000..286b04bc --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/building.md @@ -0,0 +1,150 @@ +--- +title: 构建应用 +--- + +## EAS Build {#eas-build} + +EAS Build 是 `expo build` 的升级版本。该服务有助于为您的 Expo 和 React Native 项目构建应用程序二进制文件。在 Expo 文档中阅读更多关于它的内容 [这里](https://docs.expo.dev/build/introduction/)。 + +### 配置 {#configuration} + +让我们从配置 EAS 构建开始。查看 [这里](https://docs.expo.dev/build-reference/build-configuration/) 以查看 Expo 的完整指南。 + +#### 构建设置 {#build-setup} + +在 `/frontend` 目录中运行以下命令： + +```bash +eas build:configure +``` + +运行该命令时，EAS CLI 通常会执行以下操作： + +1. 它会提示您输入 EAS 项目 ID，要么使用现有 ID（如果您有的话），要么创建一个新的。然后它会自动在 `app.json` 中添加 `expo.extra.eas.projectId` 字段。 +2. 如果 `app.json` 中没有提供 `android.package` 和 `ios.bundleIdentifier`，它会提示您指定这两个值。请注意，这两个值不必相同。 +3. 如果 `eas.json` 文件不存在，它会创建一个新的。但是我们已经为您设置好了，所以您不需要担心创建一个。 + +您可以看到运行命令后 `app.json` 中的值已经更新。 + +#### 配置变量 {#configuration-values} + +:::info +当你发布应用时，需要将 Prose 部署到一个可公开访问的地方，比如 AWS 或 DigitalOcean 这样的云托管服务商。如果 Prose 只在你的本地机器上运行，那么下载你的应用的用户将无法使用它。 +如果你还没有部署 Prose，请查看[此文档](deployment)。 + +在 Lexicon 的原始版本中，**Prose URL** 是在 `frontend/.env` 中指定的。不过，作为迁移到 Expo 的 EAS 功能的一部分，我们将配置集中到了 `frontend/Config.ts` 中，以免你需要在多个地方维护它，正如[Expo 文档](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update)中所建议的那样。 +::: + +接下来，在 `Config.ts` 中为你的构建配置 **Prose URL**。你可以为每个构建通道设置不同的 URL。你不需要调整 `localDevelopment` 中的值，因为它仅在开发时使用，而不是在构建应用时使用。 + +```ts +const config = { + // ... + buildChannels: { + preview: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + production: { + proseUrl: 'http://PLACEHOLDER.change.this.to.your.prose.url', + }, + }, +}; +``` + +### 运行构建 {#run-a-build} + +#### 为两个平台构建 {#build-for-both-platforms} + +```bash +eas build --platform all +``` + +```bash +eas build -p all +``` + +#### iOS only {#ios-only} + +```bash +eas build --platform ios +``` + +#### Android only {#android-only} + +```bash +eas build --platform android +``` + +#### 使用特定配置运行构建 {#run-a-build-with-a-specific-profile} + +```bash +eas build --platform all –-profile +``` + +```bash +eas build -p all –e +``` + +:::note +在未指定 `--profile` 的情况下，EAS CLI 将默认使用 `production` 配置。 +::: + +### 构建配置文件 {#build-profiles} + +构建配置文件用于在构建移动应用时为不同场景分组配置值。 + +你可以在 [这里](https://docs.expo.dev/build/eas-json/) 找到更多细节。 + +`eas.json` 文件可以包含多个构建配置文件。它通常包含 3 个配置文件：**preview**、**development** 和 **production**。 + +#### 1. 预览 {#1-preview} + +目的：在类似生产的环境中进行内部测试应用。 + +在使用生产配置文件构建应用之前，建议先尝试使用预览配置文件构建。这样，您可以确保应用在准备发布之前能够正常运行。 + +对 Android 的构建类型是 **APK** 文件，而对 iOS 的构建类型是可以安装在模拟器上的格式。 + +这是因为在 `eas.json` 中指定了 `ios.simulator` 选项： + +```json + "ios": { + "simulator": true + }, +``` + +如果您想在真实设备上运行预览构建，您需要拥有一个 Apple 帐户，并且该帐户必须具有 Apple Developer Enterprise Program 成员资格。然后在 `eas.json` 中添加 `ios.enterpriseProvisioning` 值： + +```json + "ios": { + "enterpriseProvisioning": "universal" + } +``` + +对于 `preview` 构建配置文件，我们已经将分发模式设置为 [internal](https://docs.expo.dev/build/internal-distribution/)。这确保了 EAS 构建提供了可共享的构建 URL，并提供了运行构建的说明。 + +此方法可以让我们在不提交到 App Store 或 Play Store 的情况下测试应用。 + +#### 2. 开发 {#2-development} + +目的：使调试更容易。Expo 将自动在构建中包含开发人员工具。正如你可能已经猜到的，这种构建永远不应发布到任何应用商店。 + +开发构建依赖于 [expo-dev-client](https://docs.expo.dev/development/introduction/)，因此如果需要，Expo 将提示我们安装该库。 + +与预览构建类似，您可以添加上面提到的 iOS 选项来在模拟器或真实设备上运行它们。 + +#### 3. 生产 {#3-production} + +目的：用于提交到 App Store 和 Play Store——作为公开发布，或作为各自生态系统中的测试的一部分。 + +要想使用这样的的构建，必须通过对应的应用商店进行安装。 + +在运行构建之后，您会看到 iOS 和 Android 版本号已自动递增。正如您可能期望的那样，这是因为 `autoIncrement` 已设置为 `true`。 + +需要注意的是，这种行为仅适用于 TestFlight 和内部测试，因此您需要确保在 `app.json` 中手动递增 `expo.version` 以进行公开发布。Expo 提供了更多关于这个主题的 [文档](https://docs.expo.dev/build-reference/app-versions/)。 + +## 构建完成！ {#the-build-is-complete} + +恭喜！您现在可以与大家分享安装链接，让他们试用这个应用。 + +在下一节中，您将学习如何将您的应用程序[发布](publishing)到 App Store 和 Play Store！ diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/install-prose.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/install-prose.md new file mode 100644 index 00000000..992c44be --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/install-prose.md @@ -0,0 +1,358 @@ +--- +title: 配置 Prose GraphQL API +--- + +现在有了一个运行中的 Discourse 实例可以交互，我们可以继续设置 Prose GraphQL 服务器。 + +回顾一下，Prose 是 Lexicon Stack 的一部分。 + +它负责在 Discourse 之上提供一个 [GraphQL](https://graphql.org/) 接口，Lexicon 移动应用可以与之交互。 + +想要了解更多信息，请查看 [概念和架构](../concepts)。 + +## 设置 Prose 的方法 {#approaches-for-setting-up-prose} + +如果你的 Discourse 实例正在本地运行，那么你应该也在本地设置 Prose 服务器。 + +否则，让远程的 Prose 服务器与本地的 Discourse 服务器通信将是不必要的额外工作。 + +不过，如果你已经在云中设置了 Discourse 实例，那么你可以选择在本地或云中运行 Prose 服务器。 + +如果你想在云中安装它，你需要设置一个额外的服务器 - 类似于设置 Discourse 的方式。如果你还不熟悉这个过程，可以回到页面 [设置云服务器（可选）](setup-cloud-server)。 + +当然无论你选择在哪里托管 Prose，你都应该考虑如何在该机器上安装它。 + +第一种方法，我们推荐使用 **[Docker](https://www.docker.com/)**。 + +当然另一种方法是手动安装，而不是使用容器。 + +## 使用 Docker 安装 Prose {#install-prose-using-docker} + +我们推荐使用 Docker 的原因是因为你不必担心如何在你的机器上配置 Prose。 + +我们已经将 Prose 发布到了 [Docker Hub](https://hub.docker.com/)，这意味着你可以轻松地拉取它并运行它。我们将在下面指导你如何操作。 + +### 安装 Docker {#install-docker} + +首先，就像设置 Discourse 一样，你需要确保 Docker 已经安装在你的机器上。 + +如果你不确定如何操作，可以查看 [Docker 安装页面](https://www.docker.com/get-started) 上的说明。 + +### 拉取并运行 Prose GraphQL API 镜像 {#pull-and-run-the-prose-graphql-api-image} + +成功安装 Docker 后，你可以使用下面的命令运行 Prose GraphQL 镜像。 + +只需记住在运行命令之前，根据你的环境调整一些 **环境变量*。 + +``` +$ docker run -d \ + -e PROSE_DISCOURSE_HOST=https://meta.discourse.org \ + -e PROSE_APP_PORT=80 \ + -p 5000:80 \ + --name prose-graphql \ + kodefox/prose +``` + +上面的命令将负责拉取 Prose GraphQL Docker 镜像、构建它并在容器中运行它。 + +为了帮助你理解指令，让我们逐行分解。 + +```bash +docker run -d +``` + +这个命令告诉 Docker 以 **detached mode** 运行我们的镜像。这类似于将一个进程放到后台。 + +```bash +-e PROSE_DISCOURSE_HOST=https://meta.discourse.org +-e PROSE_APP_PORT=80 +``` + +`-e` 标志告诉 Docker 我们想要在容器中设置或覆盖某些环境变量的值。 + +在这种情况下，我们告诉 Prose 与运行在 `https://meta.discourse.org` 的 Discourse 实例进行交互，并且 Prose 应该在容器内部的 `80` 端口上运行。 + +``` +-p 5000:80 +``` + +接下来，我们告诉 Docker 我们想要将主机上的哪些端口映射到容器中。 + +前一步中，我们已经确定 Prose 将在内部的 `80` 端口上运行。通过上面的命令，我们告诉 Docker 将容器的 `80` 端口映射到主机的 `5000` 端口上。 + +这意味着 Prose 将在主机的 `5000` 端口上可访问。 + +所以，如果你在本地运行这个命令，你可以在 `http://localhost:5000` 上与 Prose 交互。 + +如果你在云上运行它，比如在一个域名为 `https://prose.mydiscussions.com` 的域上，你可能希望它监听 `443` 端口，这样用户就不必在 URL 中输入端口号。 + +### 配置 Prose {#configure-prose} + +如上所述，你可以通过环境变量配置 Prose。 + +你可以在 Prose [环境变量](../env-prose) 页面找到所有环境变量的详细列表。 + +在这种情况下，你只需要为 `PROSE_DISCOURSE_HOST` 设置一个值，这将告诉 Prose 与哪个 Discourse 实例进行交互。 + +除此之外，如果你想设置不同的端口映射，你可以调整 `docker run` 命令的 `-p` 标志为其他值，比如： + +```bash +-p 8080:80 +``` + +## 手动安装 {#install-manually} + +这一部分，无论是在本地还是远程云服务商上，都需要你安装和配置必要的依赖项来从头开始构建和运行 Prose。 + +### 配置开发设备 + +如果你还没有给 Prose 配置好开发设备，可以按照 [设置开发设备](setup) 页面的指导进行操作。 + +完成之后，你将在开发设备上有一个本地的 Lexicon 仓库副本。 + +### 配置环境变量 {#configure-environment-variables} + +Prose GraphQL API 至少需要你提供一个可访问的 Discourse 实例的 URL 才能正常运行。 + +因为我们是手动操作，你需要用另一种方式指定，而不是像在 Docker 中那样。 + +稍后构建了 Prose 之后，在启动服务器时可以直接提供此 URL。 + +```bash +PROSE_DISCOURSE_HOST=https://discourse.mysite.com node lib/index.js +``` + +不过，你可能会发现使用我们为 `.env` 文件设置的支持更合理一些。 + +切换到仓库的 `api/` 目录，整个 Prose 代码库都在这个目录中。 + +``` +$ cd api/ +``` + +接下来，你需要创建一个 `.env` 文件。只需使用以下命令将模板文件 `.env.example` 复制到 `.env` 文件中。 + +``` +$ cp .env.example .env +``` + +之后，如你所料，你需要调整 `.env` 文件，使其包含特定于你的项目的值。 + +```bash +PROSE_DISCOURSE_HOST= +PROSE_APP_PORT= +``` + +正如我们在 Docker 部分中所述，你可以在 [Prose 环境变量](../env-prose) 页面找到所有环境变量的详细列表。 + +### 启动 Prose GraphQL API {#launch-the-prose-graphql-api} + +:::info +此时你应该已经安装了项目的依赖。 + +如果你遇到任何关于缺少包的错误，请返回到 [配置开发设备](setup) 页面查看指导。 +::: + +如果你只是想快速启动 Prose 来查看一下，只需从 `api/` 目录运行： + +```bash +$ npm run dev +``` + +这将准备并启动 Prose，但这种方式并不适合生产环境。 + +有很多方法可以在后台启动一个进程运行 Prose GraphQL API。 + +一种是使用 **[Tmux](https://github.com/tmux/tmux)**, 它可以将进程从终端中分离出来，让你在关闭它的情况下但保持 Prose 运行。 + +另一种方法是使用 **[PM2](https://pm2.keymetrics.io/)**，这是一个用于在生产环境中运行 Node 进程的复杂工具集。 + +#### 使用 Tmux {#using-tmux} + +**Tmux** 可以将进程从其控制终端中分离出来，使会话保持活动状态而不可见。 + +要开始，需要在你的机器上安装 `tmux`。 + +如果你不确定如何安装 tmux，可以查看 [此页面](https://github.com/tmux/tmux#installation). + +安装完成后，可以按如下方式启动它： + +```bash +$ tmux +``` + +然后用以下命令启动 Prose。 + +```bash +$ npm run dev +``` + +如果你想从当前会话中分离，按下 `Ctrl + B` 然后按下键盘上的 `d` 键。会话将保持在后台运行。 + +如果你想重新连接到你的上一个会话，运行以下命令。 + +``` +$ tmux a +``` + +如果你想了解更多关于 tmux 命令的信息，可以查看 [这个速查表](https://tmuxcheatsheet.com/)。 + +#### 使用 PM2 {#using-pm2} + +另一种在后台运行 Prose 的方法是使用 **pm2**（NodeJS 的进程管理器）。 + +首先，你应该已经猜到需要在你的机器上安装 `pm2`。 + +``` +$ npm install -g pm2 +``` + +安装之后，你还需要使用 `pm2` 安装 [Typescript](https://typescriptlang.org/)。 + +这是因为 Prose 是用 Typescript 编写的，这使得 PM2 可以直接运行这些 Typescript 文件（而不是先将它们转译并输出为 JS）。 + +要做到这一点，只需运行以下命令： + +``` +$ pm2 install typescript +``` + +之后，你可以在后台启动 Prose GraphQL API。 + +``` +$ pm2 start src/index.ts +``` + +要列出所有正在运行的应用程序，运行以下命令。 + +``` +$ pm2 list +``` + +这还有一些常用的命令。 + +``` +$ pm2 stop # To stop a process +$ pm2 restart # To restart a process +$ pm2 delete # To delete a process +``` + +## 测试 GraphQL API {#test-the-graphql-api} + +现在你已经成功启动了 Prose，你可以在你的 Web 浏览器中与它交互。 + +我们在构建 Prose 时使用了一些库，它自带了 [GraphiQL](https://www.graphql-yoga.com/docs/features/graphiql)。 + +这是一个在浏览器中运行的 GraphQL IDE，使得探索 GraphQL API 的文档和模式变得容易。 + +为了访问它，你需要记下你配置 API 的主机和端口号。 + +例如，如果你在本地机器上的端口 `5000` 上启动了 Prose，你可以在浏览器中输入 [http://localhost:5000](http://localhost:5000)。 + +同样，如果你在云上设置了它，并且只有一个 IP 地址，Prose 在端口 `80` 上监听，你可以在浏览器中输入 [http://174.31.92.1](http://174.31.92.1). + +GraphiQL 加载好之后，你可以测试一些示例查询和变更，包括通过 Prose 登录 Discourse。 + +### 登陆 {#login} + +:::info +如果你正在访问一个私有的 Discourse 站点，你需要记下返回的令牌以进行其他请求。请参见下面。 +::: + +``` +mutation Login { + login(email: "user@lexicon.com", password: "user_password") { + ... on LoginOutput { + token + user { + id + name + username + avatarTemplate + } + } + } +} +``` + +正如上面的通知所提到的，如果你正在与一个私有的 Discourse 站点交互，你需要为其他 GraphQL 请求提供一个令牌。 + +这个令牌是在上面的登录请求的响应中的 Base64 编码的值。 + +你可以在页面的左侧打开 HTTP Headers 部分，这部分需要 JSON，你需要添加一个包含你的令牌的 Authorization 头 + +```json +{ + "Authorization": "" +} +``` + +做完之后，你可以使用登录请求的响应中的用户信息进行其他请求。 + +### 用户配置 {#user-profile} + +``` + query UserProfile { + userProfile(username: "john_doe") { + user { + ... on UserDetail { + id + avatarTemplate + username + name + websiteName + bioRaw + location + dateOfBirth + email + } + } + } + } +``` + +### 主题细节 {#topic-detail} + +``` +query TopicDetail { + topicDetail(topicId: 1) { + id + title + views + likeCount + postsCount + liked + categoryId + tags + createdAt + postStream { + posts { + id + topicId + userId + name + username + avatarTemplate + raw + createdAt + } + stream + } + details { + participants { + id + username + avatarTemplate + } + } + } +} +``` + +### 退出登陆 {#logout} + +``` + mutation Logout { + logout (username: "john_doe") + } +``` diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/intro.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/intro.md new file mode 100644 index 00000000..3f4ccf24 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/intro.md @@ -0,0 +1,48 @@ +--- +title: 概览 +slug: /tutorial +--- + +:::info +此教程**不涵盖**实际启动应用程序的过程，以及有关部署到生产环境的某些细节。有关这些任务的支持，请参阅文档。 + +::: + +## 欢迎来到 Lexicon 教程 {#welcome-to-the-lexicon-tutorial} + +欢迎来到 Lexicon 教程！我们很高兴帮助您深入了解 Lexicon Stack，并学习如何部署它以使您和您的用户受益。 + +## 目标受众和先决条件 {#target-audience--prerequisites} + +为了完成本教程，您应该熟悉： + +- 命令行工具 +- Git 和 Github +- 配置 Discourse 实例 +- 一般服务器设置 + +在准备方面，您需要： + +- 在开发机器上安装 NodeJS + - 使用与项目版本的 Expo（即 `expo-cli`）兼容的最新版本的 Node。 +- 一个可以编辑配置文件的编辑器 + +#### 有一些疑虑？ {#have-some-concerns} + +对 Lexicon 感兴趣，但技术能力不足？我们完全理解。 + +我们的团队专注于帮助您实现您的愿景。无论您是想要定制 Lexicon，还是想要我们为您构建一个定制的解决方案，我们都可以帮助您。 + +## 下一步 {#next-steps} + +本教程将指导您完成在您的 Discourse 站点上**本地**运行整个 Lexicon Stack 的过程。 + +在教程结束时，您将能够在您的本地设备或模拟器上的 Lexicon 手机应用中与您的 Discourse 站点进行交互。 + +您还将了解： + +- 如何配置和在您的服务器上运行 Prose GraphQL API +- 如何配置和在您的设备或模拟器上运行 Lexicon 手机应用 +- 下一步如何充分利用 Lexicon + +让我们开始吧！ diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/publishing.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/publishing.md new file mode 100644 index 00000000..1518bfa3 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/publishing.md @@ -0,0 +1,97 @@ +--- +title: 发布应用 +--- + +## EAS Submit {#eas-submit} + +EAS Submit 是一个用于上传和提交应用二进制文件到 App Store 和/或 Play Store 的服务。 +在[这里](https://docs.expo.dev/submit/introduction/)了解更多关于 EAS Submit 的信息。 + +### 准备 {#prerequisites} + +- 在 App Store Connect 中注册应用，参见[这里](../app-store#register-a-new-bundle-id)的指南。 +- 在 Play Store 中注册应用，参见[这里](../play-store)的指南。 + +### 配置 {#configuration} + +在开始之前，你需要配置 `eas.json` 文件。这个文件用于指定构建配置文件和提交配置文件。 + +#### iOS {#ios} + +对于 iOS，填写你的账户信息到 `appleId`、`ascAppId` 和 `appleTeamId`： + +```json + "base": { + "ios": { + "appleId": "", + "ascAppId": "", + "appleTeamId": "" + }, + ... + }, +``` + +- **appleId**: 你的 apple ID (e.g., `john@gmail.com`). +- **ascAppId**: 你的 App Store Connect app ID. 查阅[此教程](https://github.com/expo/fyi/blob/main/asc-app-id.md)以查询你的 ascAppID (e.g., `1234567890`). +- **appleTeamId**: [在此](https://developer.apple.com/account/)查看你的 apple team ID (e.g., `12LE34XI45`). + +#### Android {#android} + +对于 Android，你需要添加一个 `.json` 密钥文件以在 Google Play Store 中进行身份验证。请按照[这个指南](https://github.com/expo/fyi/blob/main/creating-google-service-account.md)获取。然后，将 JSON 文件复制到你的 `lexicon/frontend` 目录，并将文件重命名为 `playstore_secret.json`。 + +JSON 文件如下所示： + +```json +{ + "type": "service_account", + "project_id": "", + "private_key_id": "", + "private_key": "-----BEGIN PRIVATE KEY----------END PRIVATE KEY-----\n", + "client_email": "", + "client_id": "", + "auth_uri": "", + "token_uri": "", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/lexicon%40api.iam.gserviceaccount.com" +} +``` + +配置结束，你可以开始提交应用了。 + +### 提交 {#submitting} + +使用以下命令提交构建： + +```bash +eas submit --platform ios --profile +``` + +接下来，你将看到 EAS CLI 提示询问你想提交哪个应用。 + +有 4 种可选的选项： + +- 选择 EAS 上的构建版本 +- 提供应用存档的 URL +- 提供应用二进制文件的本地路径 +- 提供 EAS 上现有构建的构建 ID + +如果你使用 EAS Build 构建了应用或者遵循了[构建你的应用](building)教程，那么请选择第一种选项，并选择你想要的版本。 + +### 提交配置文件 {#submit-profiles} + +默认情况下，`eas.json` 已经配置了两个提交配置文件，分别是 **staging** 和 **production**。 + +配置大部分相同，唯一的区别在于 Android 的提交选项。 + +- **staging** 表示该构建是 `internal` 的。这意味着使用 staging 配置提交的构建将在 Play Store 中进行内部测试。 +- **production** 表示该构建是 `production` 的，将在 Play Store 中进行公开发布。 + +对于 iOS，两个配置文件都将在提交到 TestFlight 之前提交。 + +你可以参考 Expo 文档了解更多关于[Android-specific](https://docs.expo.dev/submit/eas-json/#android-specific-options) 和 [iOS-specific](https://docs.expo.dev/submit/eas-json/#ios-specific-options) 选项。 + +## 恭喜！ {#congratulations} + +你的应用现在可以在 Play Store 和 App Store 上下载了！ + +到[下一节](updating)，也就是最后一节中了解更多关于如何更新你的应用或在线修复其中的异常。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-cloud-server.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-cloud-server.md new file mode 100644 index 00000000..4efa7f40 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-cloud-server.md @@ -0,0 +1,27 @@ +--- +title: 配置云服务器 (可选) +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +:::info +本节是为那些不太熟悉如何在云中启动新服务器的用户提供的可选部分。 + +如果您已经熟练掌握这一点，可以跳到下一节。 +::: + +## DigitalOcean 指南 {#digitalocean-guide} + +### 如何在 DigitalOcean Droplet 上设置 Ubuntu 20.04 服务器 {#how-to-set-up-an-ubuntu-2004-server-on-a-digitalocean-droplet} + +对于我们的用户来说，如果不熟悉如何在配置云服务器，我们希望为您提供一个可靠的资源，让您了解更多内容并在此过程中完成一些操作。 + +DigitalOcean 已经提供了一个出色的指南，可以帮助您完成这一过程，因此我们将链接您到该指南。 + +在本指南中，您将通过 DigitalOcean 的管理面板创建一个 Ubuntu 服务器，并配置它以与您的 SSH 密钥一起工作。 + +一旦您对如何配置云服务器有了扎实的了解，您就能更有能力为您的用户部署 Lexicon Stack。 + +您可以在下面的文章中深入了解。 + +[阅读：如何在 DigitalOcean Droplet 上设置 Ubuntu 20.04 服务器](https://www.digitalocean.com/community/tutorials/how-to-set-up-an-ubuntu-20-04-server-on-a-digitalocean-droplet) diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-discourse.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-discourse.md new file mode 100644 index 00000000..39b06663 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-discourse.md @@ -0,0 +1,304 @@ +--- +title: 配置 Discourse 站点 +--- + +要想正常配置 Lexicon，你需要先运行一个 **[Discourse](https://www.discourse.org/)** 站点，以便 Lexicon 可以与之交互。 + +为了完成这一步，你有几个选择： + +#### 选项 1：配置本地 Discourse 站点 {#option-1-setup-a-local-discourse-instance} + +第一种选择是在你的开发机器上[设置一个开发实例](#setup-discourse-locally)。这需要一些时间，可能会有一些技术难度。 + +#### 选项 2：购买 Discourse 站点或使用现有站点 {#option-2-buy-a-discourse-instance-or-use-your-existing-one} + +第二种选择是[在云上设置一个 Discourse 实例](#setup-discourse-in-the-cloud)作为一个实时、可访问的生产版本。这样做要简单得多，但显然需要花钱。 + +如果你已经有一个 Discourse 站点，那就直接使用它吧。 + +#### 选项 3：使用公开的 Discourse 站点 {#option-3-use-a-public-discourse-site} + +第三种选择是使用现有的 Discourse 站点来测试一下。 + +正如你后面会看到的，Lexicon 允许你配置指向哪个 Discourse 站点。因此，你可以指示它指向一个你没有实际拥有的公开可访问的 Discourse 站点。 + +这样做的好处是，你可以在不费力气的情况下就立即开始使用 Lexicon。 + +##### Discourse Meta {#discourse-meta} + +[https://meta.discourse.org/](https://meta.discourse.org/) + +##### Expo {#expo} + +[https://forums.expo.dev/](https://forums.expo.dev/) + +##### The Rust Programming Language {#the-rust-programming-language} + +[https://users.rust-lang.org/](https://users.rust-lang.org/) + +##### FreeCodeCamp Forums {#freecodecamp-forums} + +[https://forum.freecodecamp.org/](https://forum.freecodecamp.org/) + +## 在本地配置 Discourse {#setup-discourse-locally} + +:::note +这一小节可能会花费很长时间。根据你的机器配置，可能需要 10 - 30 分钟才能完成。 +::: + +本教程的这一部分基于 Discourse 论坛上的这篇帖子：[Beginners Guide to Install Discourse for Development using Docker](https://meta.discourse.org/t/beginners-guide-to-install-discourse-for-development-using-docker/102009)。 + +如果你遇到任何问题，可以参考原帖和后续讨论。 + +### 安装 Docker {#install-docker} + +**[Docker](https://www.docker.com/)** 是一个容器化框架，它使得构建、管理和部署应用程序堆栈变得更加简单、更加安全、更加可靠，并且可以在多个平台上重复使用。 + +在本地开发、构建和测试应用程序时，Docker 是一个非常有价值的工具，它极大地简化了整个过程。 + +在本教程中，Docker 的主要作用是不需要对我们的机器环境进行任何修改，只需安装 Docker 本身即可。 + +这与需要在物理机器上安装 Discourse 的所有依赖项不同，后者可能需要花费大量的精力才能在以后撤消。 + +如果你不确定如何安装 Docker，可以按照他们的[网站](https://www.docker.com/get-started)上的说明进行操作。 + +### 克隆 Discourse {#clone-discourse} + +Docker 运行起来后，我们就可以开始在本地设置 Discourse。 + +首先，我们需要将 Discourse 仓库克隆到本地机器上，并进入该目录。 + +``` +git clone https://github.com/discourse/discourse.git +cd discourse +``` + +请注意，该仓库较大（将近 400MB），因此这一步可能需要一些时间，具体取决于你的网络连接。 + +### 拉取、构建并启动 Discourse 开发容器 {#pull-build-and-start-the-discourse-dev-container} + +:::caution +请确保以下列出的**主机端口**在你的设备上没有被其他进程占用。 +::: + +Discourse 已经包含了一个脚本，可以帮助使用 Docker 启动整个基础设施。 + +在这个过程中，脚本将执行以下操作： + +- 从 Docker 下载必要的 "dev" 镜像来引导 Discourse +- 构建上述提到的镜像 +- 将镜像作为容器运行，将多个端口从主机映射到容器中的端口 + - 127.0.0.1:**1080**->1080/tcp + - 127.0.0.1:**3000**->3000/tcp + - 127.0.0.1:**4200**->4200/tcp + - 127.0.0.1:**9292**->9292/tcp + - 127.0.0.1:**9405**->9405/tcp +- 提示你输入管理员电子邮件地址和密码 + +要开始，请运行以下命令： + +``` +$ d/boot_dev --init +``` + +请注意，所有 Docker 镜像的磁盘空间使用量大约为 1GB。 + +这个命令将在你的终端会话中产生大量输出。在需要你提供相关信息时，输出会暂停。 + +```bash +# Output omitted +== 20200804144550 AddTitleToPolls: migrating ================================== +-- add_column(:polls, :title, :string) + -> 0.0014s +== 20200804144550 AddTitleToPolls: migrated (0.0021s) ========================= + +Creating admin user... +Email: me@me.com +Password: +Repeat password: + +Ensuring account is active! + +Account created successfully with username me +``` + +随后，它会询问你是否要将此帐户设置为管理员帐户。你需要。 + +```bash +Do you want to grant Admin privileges to this account? (Y/n) y + +Your account now has Admin privileges! +``` + +请再次注意，如上所述，上述端口目前没有被其他进程使用。 + +### 如果发生了意外情况 {#if-something-unexpected-happened} + +在这一步可能发生了一些奇怪的事情。 + +也许会出现奇怪的错误消息，或者进程根本没有显示上面显示的输出。 + +我们建议你执行以下操作： + +#### 检查是否有名为 `discourse_dev` 的 Docker 容器正在运行 {#check-if-a-docker-container-named-discourse_dev-is-running} + +```bash +$ docker ps | grep discourse_dev +CONTAINER ID IMAGE ... NAMES +dc72a4ead10f discourse/discourse_dev:release ... discourse_dev +``` + +如果有，请停止并删除容器。 + +```bash +$ docker stop discourse_dev +discourse_dev +$ docker rm discourse_dev +discourse_dev +``` + +#### 退出或杀死现有进程 {#exit-or-kill-the-existing-process} + +如果现有进程（`d/boot_dev --init`）仍在占用你的终端会话，请尝试通过 `Ctrl + C` 退出。 + +如果进程在一段时间后仍未响应 `Ctrl + C`，请找到其 PID 并使用 `kill -9` 杀死它。 + +```bash +$ ps aux | grep rails +user 81254 0.0 0.1 discourse_dev bin/rails s + +$ kill -9 81254 +``` + +#### 重启 Docker 或你的机器 {#restart-docker-or-your-machine} + +使用与你设备匹配的命令或接口，重启所有 Docker。 + +在 Docker for Mac 上，只需点击托盘图标，然后点击 Restart。 + +#### 再次运行命令 {#run-the-command-again} + +有时候这种设置会出现一些小问题。再次运行命令，看看这次是否更顺利。 + +### 如果你完全卡住了，请联系我们 {#if-youre-absolutely-stuck-reach-out} + +如果你完全卡住了，或者遇到了一些奇怪的问题，我们会很乐意帮助你。 + +### 可选：在后台运行接下来的两个命令 {#optional-run-the-next-two-commands-in-the-background} + +你可以继续阅读了解这两个命令是什么。如果你希望它们同时运行，可以通过将这两个进程放到后台来实现这一点。 + +这意味着它们不会占用你当前的会话，不需要你退出它们才能输入其他命令。 + +当你运行这个命令时，它会显示被放到后台的进程的进程 ID（PID）。 + +为了将它们重新放到前台，你可以运行 `fg` 命令，然后使用 `Ctrl + C` 或类似的信号来停止它们。 + +```bash +d/rails s & d/ember-cli & +[2] 59786 +[3] 59787 + +fg +``` + +只需注意，你看不到命令的输出，因此可能需要耐心等待几分钟，等到 Discourse 在其本地地址上可访问。 + +或者，你可以使用这些 PID 在另一个会话中直接杀死此进程： + +```bash +kill -9 59786 59787 +``` + +### 在容器中启动 Rails 服务器 {#start-the-rails-server-within-the-container} + +如果你还没有注意到，Discourse 是使用非常流行的 Web 框架 [Ruby on Rails](https://rubyonrails.org/) 构建的。 + +通过运行以下命令，你将启动 Rails 服务器，这需要一些时间，并会产生大量的输出。 + +特别是，你会看到数据库在 dev 容器引导 Discourse 服务器时被初始化。 + +运行以下命令即可开始。 + +``` +d/rails s +``` + +#### 如果你在之后的操作中无法退出进程 {#if-you-later-cant-quit-the-process} + +**注意**，有时候当你试图用 `Ctrl + C` 杀死进程时，这个命令会卡住。 + +如果发生这种情况，建议你首先停止 Docker 容器： + +```bash +docker stop docker_dev +``` + +然后，如果必要，使用 `fg` 将进程带到前台。 + +最后，要么退出你的会话（如果可能的话，比如关闭终端），要么找到 Rails 进程的 PID 并直接杀死它。 + +```bash +$ ps aux | grep rails +user 81254 0.0 0.1 discourse_dev bin/rails s + +$ kill -9 81254 +``` + +### 在容器中运行 Ember CLI {#run-the-ember-cli} + +上面的部分提到了 Ruby on Rails，它处理 Discourse 应用程序的后端方面。 + +Discourse 前端是使用 [EmberJS](https://emberjs.com/) 构建的，这是一个由多家大公司使用的全功能前端 Web 框架。 + +运行以下命令，指示 Ember CLI 启动 Discourse 前端。 + +``` +d/ember-cli +``` + +启动之后你可以在 [http://localhost:4200](http://localhost:4200) 访问 Discourse。 + +请注意，此命令的输出可能会有点令人困惑。有时候，看起来好像什么都没有发生。 + +在服务器准备就绪之前，你可能会看到几个进度指示器，以及几分钟后的空白输出。 + +输出可能会类似于以下内容： + +```bash +Build successful (72475ms) – Serving on http://localhost:4200/ + +Slowest Nodes (totalTime >= 5%) | Total (avg) +----------------------------------------------------------------------+------------------ +Babel: discourse (2) | 31501ms (15750 ms) +ember-auto-import-analyzer (11) | 10418ms (947 ms) +Bundler (1) | 6119ms +Babel: @ember/test-helpers (2) | 5075ms (2537 ms) +broccoli-persistent-filter:TemplateCompiler (3) | 4596ms (1532 ms) +``` + +## 在云上配置 Discourse {#setup-discourse-in-the-cloud} + +网络上有很多指南，指导你如何在云上设置 Discourse。 + +我们不想再写一篇，我们已经找到了我们最喜欢的一篇，分享给你，里面包含了完整的配置步骤。 + +### 由 SSDNodes 提供的指南 {#guide-by-ssdnodes} + +这篇指南由 [SSDNodes](https://www.ssdnodes.com/?e=blog&q=more-about-ssdnodes) 博客提供，[Serverwise](https://blog.ssdnodes.com/blog/)。 + +如果你不熟悉，[SSDNodes](https://www.ssdnodes.com) 是一个优秀的、性价比高的 VPS 主机提供商。 + +虽然我们最熟悉 Digital Ocean，但我们强烈建议你查看他们作为 Discourse 托管的替代方案。 + +这篇文章的标题是 [How To Install Discourse On Ubuntu](https://blog.ssdnodes.com/blog/install-discourse/)，作者是 [Joel Hans](https://blog.ssdnodes.com/blog/author/joel/)。 + +Joel 写了一篇很棒的指南。他会带你完成整个过程，包括对 Discourse 实例进行更新。 + +如果你遇到任何问题，或者有任何疑问，欢迎联系我们。 + +## 使用公开的 Discourse 站点 {#use-a-public-discourse-site} + +如果你选择使用公开的 Discourse 站点，你可以在 Lexicon 的设置中输入一个 URL，指向你想要使用的站点。 + +做完这些之后，你就可以继续下一节了。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-mobile.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-mobile.md new file mode 100644 index 00000000..1ea1efd2 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup-mobile.md @@ -0,0 +1,115 @@ +--- +title: 配置并启动移动应用 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +完成上一小节之后，你的 GraphQL API 应该已经连接到你的 Discourse 站点。 + +接下来，我们将指导你通过 Prose 将 Lexicon 移动应用连接到你的 Discourse 站点。 + +### 配置移动应用 {#mobile-app-configuration} + +:::note +在最初的 Lexicon 中，**Prose URL** 是在 `frontend/.env` 中指定的。但是，作为迁移到 Expo 的 EAS 功能的一部分，我们将配置集中到 `frontend/Config.ts` 中，以省去您在多个地方维护它的麻烦，正如[Expo 文档](https://docs.expo.dev/build-reference/variables/#can-i-share-environment-variables-defined-in-easjson-with-expo-start-and-eas-update)中建议的那样。 +::: + +在启动本地版本的 Lexicon 移动应用之前，你需要至少配置一个信息。 + +Lexicon 移动应用完全依赖于正在运行的 Prose GraphQL API 实例，以便从你的 Discourse 实例中检索数据。 + +因此，你需要指示它如何定位正在运行的 Prose 服务器。 + +#### 通过 `frontend/Config.ts` 配置 `proseUrl` {#configuring-proseurl-via-config} + +:::caution + +##### `proseUrl` 要求 {#proseurl-requirements} + +请注意，`proseUrl` **必须**以 `http://` 或 `https://` 开头。否则，移动应用在启动时会抛出错误。 +::: + +`Config.ts` 包含了 `config` 对象，允许你在开发和构建移动应用时指定每个场景的 Prose URL。 + +具体要配置值是 `proseUrl`，它包含在 `config` 对象所表示的多个场景中。 + +```ts +const config = { + localDevelopment: { + proseUrl: 'http://localhost:8929', + }, + buildChannels: { + preview: { + proseUrl: 'https://preview.myserver.com:8080/subpath', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +如上所述，`config` 对象允许我们为多个场景表达配置值，这些场景包括： + +- `localDevelopment`：在本地开发应用时。当构建通道未知时，此配置也会被用作默认值。 +- `buildChannels`：在使用 EAS CLI 构建应用时，用于按构建通道定义配置。 + +`buildChannels` 使用 Expo 的构建通道（通常为 `preview` 和 `production`）作为其键值。 + +`buildChannels` 中的每个键值都映射到一个特定的 Prose URL，该 URL 将根据你为哪个通道构建而被用于构建版本。 + +在上面的示例中，当我们创建一个 `preview` 构建时，应用将被构建并配置为连接到位于 `https://preview.myserver.com:8080/subpath` 的 Prose 服务器。 + +同样，当我们创建一个 `production` 构建时，应用将被配置为连接到位于 `https://myserver.com/api/prose` 的 Prose 服务器。 + +```ts +const config = { + localDevelopment: { + proseUrl: 'https://myserver.com/api/prose', + }, + buildChannels: { + preview: { + proseUrl: 'https://myserver.com/api/prose', + }, + production: { + proseUrl: 'https://myserver.com/api/prose', + }, + }, +}; +``` + +##### 端口号 {#port-number} + +请注意，如果你的 Prose 服务器不在端口 `80` 或 `443` 上运行，你还需要通过 `proseUrl` 指定 **端口号**。 + +例如，如果你在本地的端口 `8929` 上启动了一个 Prose 服务器，并尝试使用 `expo start` 运行它，那么你的 `Config.ts` 文件需要在 `localDevelopment.proseUrl` 下囊括 `http://myserver.com:8929/api/prose`。 + +### 启动移动应用 {#launch-the-mobile-app} + +配置完成之后你一定会想要启动移动应用来测试它是否与正确的 Prose 服务器通信。 + +为了做到这一点，你可以简单地从项目根目录运行以下命令： + +```bash +npm run --prefix frontend start +``` + +Expo 开发服务器应该会启动，你可以按照指示在模拟器或实际设备上运行应用。 + +#### 异常排查 {#troubleshooting} + +如果应用在加载时抛出错误，你应该根据收到的消息再次检查你指定的配置值。 + +如果应用加载了，但你无法连接，你应该验证以下内容： + +- 你的 Prose 服务器是否正在运行，并且在你在 `Config.ts` 中指定的端口上运行 +- 你的 Prose 服务器是否配置为指向一个可访问的 Discourse 实例 +- 你的 Discourse 实例是否正确运行 + +## 干得漂亮！ {#nice-work} + +到此为止，你已经完成了很多工作。 + +你开始的 Discourse 服务器现在可以通过一个全新的原生移动应用访问，你可以自由定制它以适应你的需求。 + +在下一部分教程中，我们将简要讨论这个主题：通过[白标](white-label)为你的品牌定制移动应用。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup.md new file mode 100644 index 00000000..3698d503 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/setup.md @@ -0,0 +1,96 @@ +--- +title: 配置开发环境 +--- + +## 安装 NodeJS {#install-nodejs} + +如果您尚未安装 NodeJS，请在您的计算机上安装 NodeJS。 + +Lexicon 配置所需的工具主要依赖于 Node 和 npm。 + +如果您不知道如何安装 NodeJS，您可以按照 [NodeJS 网站](https://nodejs.org/en/download/) 上的说明进行操作。 + +### 支持的 Node 版本 {#supported-node-versions} + +建议您使用与项目的 Expo 版本兼容的最新 Node 版本执行本教程。 + +你可以在 [frontend/package.json](https://github.com/lexiconhq/lexicon/blob/master/frontend/package.json) 中查看依赖及其版本。 + +如果你当前的开发环境不方便切换 Node 版本，我们建议使用 [`nvm`](https://github.com/nvm-sh/nvm) 快速切换 Node 版本。 + +### 安装 yarn（如果您更喜欢） {#install-yarn-if-you-prefer} + +Lexicon 不使用 [Yarn](https://yarnpkg.com/)（Node 的另一种包管理器）的任何特殊功能。如果您更喜欢它，它将与运行 `npm install` 一样工作。 + +为了编写本教程，我们将演示所有命令使用 `npm`。 + +### 克隆 Lexicon 仓库 {#clone-the-lexicon-repository} + +在您的开发机器上选一个想存储此代码仓库的位置，克隆 Lexicon 仓库并 `cd` 进入其中。 + +```sh +git clone git@github.com:lexiconhq/lexicon.git +cd lexicon +``` + +### 安装依赖 {#install-dependencies} + +接下来，安装 Lexicon 的依赖项： + +```sh +npm install +``` + +这将为移动应用和后端 GraphQL API Prose 安装依赖项。 + +### 安装 Expo CLI {#install-the-expo-cli} + +[Expo](https://expo.io/) 是 Lexicon 用来开发和构建移动应用的绝佳工具链。 + +我们稍后将使用 Expo CLI 来启动移动应用 - 无论是在您的设备上还是在模拟器中。 + +您可以使用以下命令安装 Expo CLI： + +```sh +npm install --global expo-cli +``` + +更多信息请参阅 [Expo 文档](https://docs.expo.io/)。 + +然后，使用以下命令验证 Expo 是否在您的 `PATH` 中： + +```sh +$ expo --version + +``` + +### 安装 EAS CLI {#install-the-eas-cli} + +[Expo 应用服务（EAS）](https://expo.dev/eas/) 是 Expo 和 React Native 应用的一组集成云服务。 + +我们将使用 EAS CLI 来构建和发布移动应用。 + +您可以使用以下命令安装 EAS CLI： + +```sh +npm install --global eas-cli +``` + +更多信息请参阅 [Expo 文档](https://docs.expo.dev/eas/)。 + +然后，使用以下命令验证 EAS 是否在您的 `PATH` 中： + +```sh +$ eas --version +eas-cli/ +``` + +### 准备就绪！ {#ready-to-go} + +这就是我们在本步骤中所需要的全部内容。 + +随后，我们将介绍如何在云服务商上配置 Discourse 服务器。此内容属于可选内容，如果您已经熟悉此过程或无需此操作，可以跳过。 + +之后，我们将探讨如何准备 Discourse 以连接 Lexicon 移动应用。 + +如果你还没有配置好 Discourse 服务器，我们将介绍如何配置。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/updating.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/updating.md new file mode 100644 index 00000000..d9c01831 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/updating.md @@ -0,0 +1,68 @@ +--- +title: 更新应用 +--- + +## EAS Update {#eas-update} + +EAS Update 是 `expo publish` 的升级版本。该服务有助于使用 `expo-updates` 库更新项目。 + +EAS Update 使您能够在不完整的应用商店提交新应用的情况下向用户推送快速修复。 + +使用 EAS Update，无需重新编译应用的非本机部分，例如 TypeScript 代码、样式或图像资产。[点击这里](https://docs.expo.dev/eas-update/introduction/)了解更多关于 EAS Update 的信息。 + +:::note +在使用 EAS Update 之前，您需要使用 [EAS Build](building) 构建应用。 +::: + +### 配置 {#configuration} + +让我们通过配置 EAS Update 来开始。欢迎查看 Expo 的[完整指南](https://docs.expo.dev/build-reference/build-configuration/)以获取更多详细信息。 + +```bash +eas update:configure +``` + +运行此命令将在 `app.json` 中添加 `expo.updates.url` 和 `runtimeVersion.policy`。 + +:::caution + +如[Expo文档](https://docs.expo.dev/build/updates/#previewing-updates-in-development-builds)中所述，添加 `app.json` 中的 `runtimeVersion` 字段后，您将无法在 Expo Go 中启动应用（使用 `expo start`）。建议使用 `expo-dev-client` 代替创建开发构建。 + +```bash +eas -p all -e development +``` + +或者，如果您仍希望使用 Expo Go，请在运行 `expo start` 之前从 `app.json` 中删除 `runtimeVersion` 字段。 +::: + +### 更新 {#updating} + +在进行必要更改后，您可以使用以下命令推送更新： + +```bash +eas update –-branch –-message “” +``` + +这里的分支名称与构建应用时的构建配置名称相同。例如，使用以下命令构建应用： + +```bash +eas build –p all –e preview +``` + +您可以稍后使用以下命令更新： + +```bash +eas update –-branch preview –-message “Fixing typos” +``` + +更新结束后，重启已安装的应用两次以查看更新。 + +## 大功告成！ 🙌 {#all-done- + +这就是本教程的全部内容。干得漂亮！ + +希望本教程能帮助您更好地了解 Lexicon 并学会如何使用它。 + +如果您还有疑惑，请查看[Lexicon 文档](../)以更深入地了解项目及其工作原理。 + +如果您有任何问题、评论、反馈或想要提交贡献，请在 Github 上联系我们！ diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/white-label.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/white-label.md new file mode 100644 index 00000000..5646f29a --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/tutorial/white-label.md @@ -0,0 +1,82 @@ +--- +title: 个性化应用 +--- + +## 自定义启动画面和应用图标 {#customize-the-splash-screen-and-app-icon} + +为了将应用定制为您自己的品牌，您可能希望为**启动画面**和**应用图标**提供自己的资源。 + +**启动画面** - 是应用启动时显示的内容。有些应用在将应用置于后台时也会显示这个内容，以帮助隐藏私人信息。 + +**应用图标** - 是用于在用户设备上表示应用的内容，例如在主屏幕上和在设备设置中列出应用时。 + +这两个资源通常包含您的标志或其他形式的标志。例如，Gmail 应用的 App 图标是一个多色信封的轮廓。然后，在启动 Gmail 应用时，您会注意到启动画面包含 App 图标的更大版本。 + +### 自定义启动画面 {#customizing-the-splash-screen} + +:::info +Expo 目前尚不支持启动画面的暗色模式。 +::: + +在移动应用中用于启动画面的资源位于 `frontend/assets/images/splash.png` 和 `frontend/assets/images/splashDark.png`。 + +亮色模式和暗色模式的启动画面资源都已经准备好了。 + +但是 Expo 目前不支持启动画面的暗色模式。我们只是包含了这两个资源，以便在 Expo 以后支持时可以使用。 + +在此期间，您可以调整 `splash.png` 来影响显示的资源。 + +为了更改它，您可以简单地用您自己的 `splash.png` 文件替换现有文件。 + +要了解有关启动画面图像大小和其他详细信息，请参阅[Expo 启动画面指南](https://docs.expo.io/guides/splash-screens/)。 + +#### 进一步配置 {#futher-configuration} + +要调整启动画面图像的大小并更改其背景颜色，首先打开 `frontend/app.json` 并找到其中的 `"splash"` 字段。 + +如下面的摘录所示，有多个字段可用于进一步调整启动画面： + +```json +"splash": { + "image": "./assets/splash.png", + "resizeMode": "contain", + "backgroundColor": "#FFFFFF" +}, +``` + +**image** + +`image` - 调整用于定位启动画面图像的路径。 + +**resizeMode** + +**resizeMode** - 允许您管理启动画面图像的调整大小方式以保持其纵横比： + +- `contain` - 调整图像大小以确保整个图像可见。这是默认设置。 +- `cover` - 调整图像大小以覆盖整个容器（在这种情况下是整个屏幕），通过拉伸或裁剪图像来实现。 + +有关 `contain` 和 `cover` 行为的更多详细信息在之前提到的[Expo 启动画面指南](https://docs.expo.io/guides/splash-screens/)中有介绍。更详细的解释可以阅读[这篇文章](http://blog.vjeux.com/2013/image/css-container-and-cover.html)。 + +**backgroundColor** + +`backgroundColor` - 允许您指定启动画面图像背后的背景颜色。删除此值将导致使用默认值，即白色背景颜色。 + +### 自定义应用图标 {#customizing-the-app-icon} + +在 Lexicon 中自定义应用图标的过程与自定义启动画面几乎相同。 + +移动应用的图标资源位于 `frontend/assets/icon.png`。要自定义它，只需用您自己的 `icon.png` 文件覆盖该文件。 + +## 进一步定制 {#further-customization} + +我们在[白标](../white-labeling)部分的文档中更详细地介绍了如何自定义您的应用。 + +特别是，这包括自定义和扩展主题的颜色调色板、图标，甚至字体。 + +如果您需要任何文档中尚未涵盖的内容，请与我们联系，我们将看看如何帮助您实现。 + +## 棒极了 {#awesome-work} + +现在您的应用看起来很酷 😎。但是，它只能由您访问 + +接下来，我们将介绍如何实际[构建您的应用](building)，以便您可以与他人分享。 diff --git a/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/white-labeling.md b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/white-labeling.md new file mode 100644 index 00000000..6b601a55 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-plugin-content-docs/version-2.0.0/white-labeling.md @@ -0,0 +1,13 @@ +--- +title: 概览 +--- + +The Lexicon 移动应用程序允许您通过一种称为**白标**的过程来自定义其外观。 + +如果您对这个术语不熟悉，它本质上是为您的用户在现有应用程序上定制品牌。 + +白标功能允许您使用自己的标志、应用程序图标、颜色主题、字体等配置应用程序。 + +这样，您的用户就不会知道 Lexicon 团队构建了这个应用程序。它的外观将完全定制为您的品牌。 + +要了解有关白标 Lexicon 移动应用程序的更多信息，请继续下一节。 diff --git a/documentation/i18n/zh/docusaurus-theme-classic/footer.json b/documentation/i18n/zh/docusaurus-theme-classic/footer.json new file mode 100644 index 00000000..9dcf7e02 --- /dev/null +++ b/documentation/i18n/zh/docusaurus-theme-classic/footer.json @@ -0,0 +1,6 @@ +{ + "copyright": { + "message": "Copyright © 2024 Lexicon. MIT License. Built with ❤️ by KodeFox.", + "description": "The footer copyright" + } +} diff --git a/documentation/i18n/zh/docusaurus-theme-classic/navbar.json b/documentation/i18n/zh/docusaurus-theme-classic/navbar.json new file mode 100644 index 00000000..1cd04e3b --- /dev/null +++ b/documentation/i18n/zh/docusaurus-theme-classic/navbar.json @@ -0,0 +1,22 @@ +{ + "title": { + "message": "Lexicon", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "Lexicon Logo", + "description": "The alt text of navbar logo" + }, + "item.label.Documentation": { + "message": "文档", + "description": "Navbar item with label Documentation" + }, + "item.label.Tutorial": { + "message": "教程", + "description": "Navbar item with label Tutorial" + }, + "item.label.GitHub": { + "message": "GitHub", + "description": "Navbar item with label GitHub" + } +} diff --git a/documentation/package.json b/documentation/package.json index 87eb61bd..a0cca266 100644 --- a/documentation/package.json +++ b/documentation/package.json @@ -9,7 +9,9 @@ "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", - "serve": "docusaurus serve" + "serve": "docusaurus serve", + "write-translations": "docusaurus write-translations", + "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { "@docusaurus/core": "^2.4.3", diff --git a/documentation/versioned_docs/version-2.0.0/app-store.md b/documentation/versioned_docs/version-2.0.0/app-store.md index f91b5fa0..9c818e40 100644 --- a/documentation/versioned_docs/version-2.0.0/app-store.md +++ b/documentation/versioned_docs/version-2.0.0/app-store.md @@ -54,9 +54,7 @@ You can follow these instructions to get one. - **Bundle ID**: Select `Explicit`, and then insert then insert your bundle ID in the input field. -- Capabilities - - - You can leave this section empty. + - Capabilities: You can leave this section empty. ## Add a New App in App Store Connect diff --git a/documentation/versioned_docs/version-2.0.0/assets.md b/documentation/versioned_docs/version-2.0.0/assets.md index a24dcad0..742a74f7 100644 --- a/documentation/versioned_docs/version-2.0.0/assets.md +++ b/documentation/versioned_docs/version-2.0.0/assets.md @@ -32,7 +32,7 @@ The assets are located in the `frontend/assets/icons` folder. If you want to add There are some standards applied to the icons, such as: -#### Uniform Icon Size to Maintain Visual Consistency +### Uniform Icon Size to Maintain Visual Consistency The UI is designed around the default base dimensions of 28x28px for icons. @@ -40,7 +40,7 @@ If you adjust this, you may need to modify other aspects of the theme or fonts i Similarly, if you provide a new icon that does not conform to these dimensions, you may run into visual inconsistencies. -#### SVG Icons have their Fill Color Controlled via `currentColor` +### SVG Icons have their Fill Color Controlled via `currentColor` If you are adding a new icon that you expect to interact with theme's colors, ensure that its color is not hard-coded, and is instead set to `currentColor`. diff --git a/documentation/versioned_docs/version-2.0.0/concepts.md b/documentation/versioned_docs/version-2.0.0/concepts.md index e1d3f780..8f511fb2 100644 --- a/documentation/versioned_docs/version-2.0.0/concepts.md +++ b/documentation/versioned_docs/version-2.0.0/concepts.md @@ -18,7 +18,7 @@ The core team, as well as members of the [support forum](https://meta.discourse. To help you simplify the process for you, Prose strives to normalize a subset of the API. We have done so with the hope that it will save you some time as you develop against Discourse. -#### GraphiQL +### GraphiQL Prose's GraphQL implementation includes an [in-browser GraphQL IDE](https://www.graphql-yoga.com/docs/features/graphiql), known as [GraphiQL](https://github.com/graphql/graphiql), which allows developers to easily reference the entire documentation and schema and make queries against a running Discourse instance. @@ -26,7 +26,7 @@ Prose's GraphQL implementation includes an [in-browser GraphQL IDE](https://www. This means you can rapidly get a clear understanding of how a method behaves—and what parameters it requires—without digging through support posts or reverse-engineering the REST API. -#### Why GraphQL? +### Why GraphiQL? There is no shortage of articles about both the [benefits](https://www.howtographql.com/basics/1-graphql-is-the-better-rest) and [tradeoffs](https://lwhorton.github.io/2019/08/24/graphql-tradeoffs.html) of GraphQL. @@ -38,7 +38,7 @@ Having said that, we chose to build Lexicon with it for two primary reasons. 2. The tooling, libraries, and auto-generated documentation provide out-of-the box benefits which we can pass onto others with no additional effort. -#### Why Expo? +## Why Expo? [Expo](https://docs.expo.io/) is both a framework and a platform for building universal React applications. In particular, it provides a superior development experience when building mobile apps with React Native. diff --git a/documentation/versioned_docs/version-2.0.0/discourse-plugin-enable.md b/documentation/versioned_docs/version-2.0.0/discourse-plugin-enable.md index e33e202a..b3023e29 100644 --- a/documentation/versioned_docs/version-2.0.0/discourse-plugin-enable.md +++ b/documentation/versioned_docs/version-2.0.0/discourse-plugin-enable.md @@ -10,15 +10,13 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; After you have confirmed the plugin has been installed and your Discourse instance is running again, you can follow these steps to enable the plugin: 1. As an admin user, access your Discourse admin dashboard. - 2. Navigate to the `Plugins` tab. -You'll notice that the `discourse-lexicon-plugin` is not enabled yet. - -Plugin Admin Page + You'll notice that the `discourse-lexicon-plugin` is not enabled yet. + + Plugin Admin Page 3. Click on the `Settings` button for the `discourse-lexicon-plugin` entry. - 4. Select the feature you want to enable and turn it on. ##### Push Notifications diff --git a/documentation/versioned_docs/version-2.0.0/discourse-plugin-installation.md b/documentation/versioned_docs/version-2.0.0/discourse-plugin-installation.md index 911770b1..e9aa236e 100644 --- a/documentation/versioned_docs/version-2.0.0/discourse-plugin-installation.md +++ b/documentation/versioned_docs/version-2.0.0/discourse-plugin-installation.md @@ -65,8 +65,8 @@ Please be aware that rebuilding your site will result in your site going offline #### Precautionary Measures 1. Before installing the plugin or performing any site rebuild, it is highly recommended to create a backup of your Discourse site. -1. It is advisable to upgrade your Discourse installation and all existing plugins to their latest versions before attempting to install this plugin. -1. Although rare, there may be situations where the site does not come back online after the rebuilding process, and requires further troubleshooting to revive. +2. It is advisable to upgrade your Discourse installation and all existing plugins to their latest versions before attempting to install this plugin. +3. Although rare, there may be situations where the site does not come back online after the rebuilding process, and requires further troubleshooting to revive. - This is always a risk when installing a plugin or performing any task that requires rebuilding the app. - We recommend that you perform these changes at a time that minimizes the users affected and that you have a well-defined contingency plan in place if something goes wrong. diff --git a/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md b/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md index 60d0d6bd..bd4181e2 100644 --- a/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md +++ b/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/enable-email-deep-linking.md @@ -9,20 +9,16 @@ This guide will walk you through the necessary steps to activate email deep link ## Steps 1. Ensure the [Lexicon Discourse plugin](../../discourse-plugin-installation.md) is installed and activated. +2. Access your Discourse admin dashboard. +3. Navigate to the `Plugins` section. -1. Access your Discourse admin dashboard. - -1. Navigate to the `Plugins` section. - - + 4. Locate the `discourse-lexicon-plugin` and click on the `Settings` button. - 5. Fill in the `lexicon app scheme` setting with your app scheme. The app scheme is required to enable email deep linking. - 6. Check the `lexicon email deep linking enabled` box in the Lexicon settings section and save your changes. - + Once the email deep linking feature is enabled, you will be able to utilize its functionality in your Discourse instance. diff --git a/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md b/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md index 06f51678..d1b5aebb 100644 --- a/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md +++ b/documentation/versioned_docs/version-2.0.0/email-deep-linking/setup/verify-email-deep-linking.md @@ -20,11 +20,11 @@ If you have not yet fulfilled all of the pre-requisites below, this test will no In order to test email deep linking properly: 1. You **must** have already published your Lexicon-powered mobile app to the App Store and/or Google Play Store. -1. You have already installed and configured the Lexicon Discourse plugin on your Discourse site. -1. You have enabled email deep linking within the Lexicon Discourse plugin settings, and the app scheme matches what you published your app with. -1. You have at least 1 mobile device with your Lexicon-powered mobile app already installed, with the correct app scheme as it was configured in Discourse. -1. You have at least 2 separate Discourse accounts to test with. -1. Ensure your Discourse site allows **mailing list mode**, and that it is turned on for the accounts you are testing with. +2. You have already installed and configured the Lexicon Discourse plugin on your Discourse site. +3. You have enabled email deep linking within the Lexicon Discourse plugin settings, and the app scheme matches what you published your app with. +4. You have at least 1 mobile device with your Lexicon-powered mobile app already installed, with the correct app scheme as it was configured in Discourse. +5. You have at least 2 separate Discourse accounts to test with. +6. Ensure your Discourse site allows **mailing list mode**, and that it is turned on for the accounts you are testing with. - If you do not do this, you will have to wait for Discourse to send its next digest email, which could take a while. ## Steps @@ -32,17 +32,17 @@ In order to test email deep linking properly: To test email deep linking within your **published** Lexicon-powered mobile app, follow these steps: 1. Ensure you have access to at least 2 separate accounts on your Discourse instance. -1. On your mobile device, open your Lexicon-powered mobile app and login using one of your accounts. +2. On your mobile device, open your Lexicon-powered mobile app and login using one of your accounts. - We'll refer to this as the **first** account. - **Note**: ensure that your email client on your mobile device will receive emails for this account. -1. Open your Discourse site in a web browser on your laptop or desktop computer. -1. Login to your **second** Discourse account in your web browser. -1. On your mobile device, using the **first** account, create a new post. -1. Now, on your laptop or desktop computer, using the **second** account, find the post you created on the mobile app and reply to it. -1. Back on your mobile device, you should receive an email notification from Discourse about the reply from the second account. -1. Click on the button that says `Visit Message` or `Visit Topic`. +3. Open your Discourse site in a web browser on your laptop or desktop computer. +4. Login to your **second** Discourse account in your web browser. +5. On your mobile device, using the **first** account, create a new post. +6. Now, on your laptop or desktop computer, using the **second** account, find the post you created on the mobile app and reply to it. +7. Back on your mobile device, you should receive an email notification from Discourse about the reply from the second account. +8. Click on the button that says `Visit Message` or `Visit Topic`. - The label depends on what activity generated the email (see screenshot below). -1. The link will first open in your mobile web browser. Provided that the Lexicon-powered mobile app is installed and matches the configured app scheme, it should automatically open your app to the relevant topic or message scene. +9. The link will first open in your mobile web browser. Provided that the Lexicon-powered mobile app is installed and matches the configured app scheme, it should automatically open your app to the relevant topic or message scene.
diff --git a/documentation/versioned_docs/version-2.0.0/play-store.md b/documentation/versioned_docs/version-2.0.0/play-store.md index 9781ea20..c54ff9cd 100644 --- a/documentation/versioned_docs/version-2.0.0/play-store.md +++ b/documentation/versioned_docs/version-2.0.0/play-store.md @@ -56,7 +56,7 @@ In the example below, we're providing our app with the ability to read and write ```json "android": { "package": "", - "permissions": [ "READ_EXTERNAL_STORAGE" , "WRITE_EXTERNAL_STORAGE" ] + "permissions": [ "READ_EXTERNAL_STORAGE" , "WRITE_EXTERNAL_STORAGE" ], "versionCode": 1, }, ``` diff --git a/documentation/versioned_docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md b/documentation/versioned_docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md index adcac398..76837882 100644 --- a/documentation/versioned_docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md +++ b/documentation/versioned_docs/version-2.0.0/push-notifications/setup/enable-push-notifications.md @@ -14,18 +14,15 @@ Below, we'll walk you through the necessary steps to activate push notifications ## Steps 1. Ensure the [Lexicon Discourse plugin](../../discourse-plugin-installation.md) is installed and activated. +2. As an admin user, access your Discourse admin dashboard. +3. Navigate to the Plugins section. -1. As an admin user, access your Discourse admin dashboard. - -1. Navigate to the Plugins section. - - + 4. Click on the `Settings` button for the `discourse-lexicon-plugin` entry. - 5. Check the `enable Push Notifications` box in the Lexicon settings section and save your changes. - + Once the push notifications setting is enabled, your users will be able to login through the mobile app and start receiving push notifications. diff --git a/documentation/versioned_docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md b/documentation/versioned_docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md index 26679ffb..f33302f8 100644 --- a/documentation/versioned_docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md +++ b/documentation/versioned_docs/version-2.0.0/push-notifications/setup/verify-push-notifications.md @@ -21,12 +21,12 @@ Additionally, **you will need at least one mobile device** for testing purposes. To test push notifications within your Lexicon-powered mobile app, follow these steps: 1. Ensure that you have completed the [Getting Started](../../quick-start) steps for Lexicon. -1. Start the Lexicon Expo app by navigating to `frontend/` and running `yarn start` from your terminal. -1. Using the Expo link or QR Code, launch the app on a real mobile device. -1. Login to the app using one of your accounts. -1. Using that account, create a post within your Discourse site -1. Using a separate account, reply to the post to trigger a notification for the first account. -1. You should receive a push notification on your phone with the reply content from the other account. +2. Start the Lexicon Expo app by navigating to `frontend/` and running `yarn start` from your terminal. +3. Using the Expo link or QR Code, launch the app on a real mobile device. +4. Login to the app using one of your accounts. +5. Using that account, create a post within your Discourse site +6. Using a separate account, reply to the post to trigger a notification for the first account. +7. You should receive a push notification on your phone with the reply content from the other account. diff --git a/documentation/versioned_docs/version-2.0.0/theming.md b/documentation/versioned_docs/version-2.0.0/theming.md index 04dbc172..122cab02 100644 --- a/documentation/versioned_docs/version-2.0.0/theming.md +++ b/documentation/versioned_docs/version-2.0.0/theming.md @@ -204,7 +204,7 @@ The `spacing` theme file defines spacing constants used throughout the Mobile Ap While the above adjustments are generally fairly simple, you can really customize the Mobile App to your heart's content (based on your skill level). -Here are some additional aexamples. +Here are some additional examples. ### Custom Fonts diff --git a/documentation/versioned_docs/version-2.0.0/troubleshooting-build.md b/documentation/versioned_docs/version-2.0.0/troubleshooting-build.md index 68d75dad..cda9b392 100644 --- a/documentation/versioned_docs/version-2.0.0/troubleshooting-build.md +++ b/documentation/versioned_docs/version-2.0.0/troubleshooting-build.md @@ -111,16 +111,16 @@ To resolve this issue, follow these steps: 2. Look for the `"expo"` section. 3. If a scheme is not present add this part in `"expo"` section -```json -"expo":{ - "name": "", - "slug": "", - "scheme": "", - "version": "1.0.0" -} -``` + ```json + "expo":{ + "name": "", + "slug": "", + "scheme": "", + "version": "1.0.0" + } + ``` -Replace `""` with the desired scheme name for your app. + Replace `""` with the desired scheme name for your app. 4. Save the changes to the `app.json` file. 5. Rebuild your app and test it again. diff --git a/documentation/versioned_docs/version-2.0.0/tutorial/setup.md b/documentation/versioned_docs/version-2.0.0/tutorial/setup.md index 20505940..9a9c3473 100644 --- a/documentation/versioned_docs/version-2.0.0/tutorial/setup.md +++ b/documentation/versioned_docs/version-2.0.0/tutorial/setup.md @@ -10,7 +10,7 @@ The tooling needed to setup Lexicon relies heavily on Node and npm. If you are unsure of how to install NodeJS, you can follow the instructions on the [NodeJS Website](https://nodejs.org/en/download/). -#### Supported Node Versions +### Supported Node Versions It is recommended that you perform this tutorial using the latest version of Node that is compatible with the the project's version of Expo. diff --git a/package.json b/package.json index 5d451f2a..d3d5a75d 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,7 @@ "docs:install": "yarn --cwd documentation install", "docs:build": "yarn --cwd documentation build", "docs:start": "yarn --cwd documentation start", + "docs:serve": "yarn --cwd documentation serve", "postinstall": "yarn --cwd api install && yarn --cwd frontend install" }, "dependencies": {