blocklet / blocklet-site Goto Github PK

• 很多的 title 和语言对不上
• 很多的 description 都没有

错误的

正确的

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: 安装 Blocklet CLI
• Content Source: developer/docs/pages/quick-start/blocklet-server/index.zh.md
• Version: 0.1.90

1. 给出的例子太少了，代码例子 + 实际链上的结算，可以列出几种场景
2. 付费组件发布流程不应该放在这里？应该是 conceptual 的
3. 建议的目录结构：
   • 基本定价模型：所有的收入都需要在 blocklet 分发链条上共享
   • 为单独购买定价
     • 调整分成比例
     • 调整分成受益人
   • 为组合购买定价
     • 固定分成
     • 浮动分成
   • 如何禁止被组合
   • 调整价格和版本号

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Build blocklet for profit
• Content Source: developer/docs/pages/how-to/profit/index.zh.md
• Version: 0.1.76

https://developer.blocklet.io/samples

• 这个页面应该有个 Description，描述下是什么？Simple blocklets with source code and published version, showcase the blocklet platform capabilities, can be used your project starter.
• 详情页的返回应该在 sidebar 和 main 的上面，而不是只在 sidebar 上面
• 详情页的内容都太单薄了，每个至少两三段，加上到开发者文档的链接

需求

来到文档首页的人，大部分可能是遇到了问题，我们把常见 Topic 列出来，再加上比较好的搜索支持，会更容易帮他们解决问题。

方案

站在开发者的角度去思考，他可能遇到哪些问题，把这些问题分类，组合成豆腐块，排列在首页。比如：开发、打包、发布、运营

• 开发阶段：如何初始化？如何管理用户？如果管理权限？如何做控制台？如何集成其他组件？如何持久化数据？如何和链交互？
• 打包阶段：Store 的要求？Logo、Screenshot、Readme，如何验证？如何作为子组件开发
• 发布阶段：如何定价？如何分成？
• 运维阶段：如何做 migration？如何升级？

参考

• https://developer.chrome.com/docs/webstore/
• https://www.gatsbyjs.com/docs

个人强烈建议参考的是 gatsby js，他的文档结构非常清晰：

• How-to guides：How
• Reference guides：Why
• Conceptual guides：What

并且层层递进：

blocklet server 每个页面里的上上下文帮助应该和文档站建立直接的联系。

包括这些地方：

上下文帮助：

首页的document 链接：

目前这些链接指向要不是老的，要不是 404

• 建议直接将 blocklet meta 替换成 blocklet.yml 或 meta.js（会有单独一节来介绍）
• footer 两种布局不能显示指定？

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Blocklet UI
• Content Source: developer/docs/pages/reference/blocklet-ui/index.zh.md
• Version: 0.1.76

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: 入门指南
• Content Source: developer/docs/pages/quick-start/index.zh.md
• Version: 0.1.90

页面地址：https://developer.blocklet.io/docs/deployment/bundle

• Bundle Blocklet @skypesky
• Deploy Blocklet to Server @linchen1987
• Publish Blocklet to Store @skypesky
• Using Github Actions @linchen1987

• Blocklet Meta 就是 blocklet.yml，我们不需要造出两个概念来，所有使用 blocklet meta 的地方我们都改成 blocklet.yml
• 所有可以链接的都应该加上链接，比如 create-blocklet，比如各种 blocklet cli 子命令
• 访问入口通常情况下不需要用户配置

• 文档结构比较清晰，但是每个小节缺少实际的例子，可以加一些代码的例子，以及钱包的截图，比如：
• 如何发送文本消息
• 如何发送带附件的消息
  • 发送 Token，链接到链
  • 发送 NFT，链接到链
  • 发送 VC，链接到链
• 如何发送带动作的消息

建议从很常见的开发者需求出发，给出实际的例子和钱包端截图

另外，广播消息如何用，可以列下场景

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: 和 DID 钱包通信
• Content Source: developer/docs/pages/how-to/notification/index.zh.md
• Version: 0.1.75

• Auth 的右侧导航显的太凌乱，api 签名不适合做标题，建议简化为函数名字或者函数用途

• component api 需要解释，给出示例
• environment 里面可以增加必要的解释
• Conceptual guides > blocklet 里面需要增加 blocklet appId、blocklet Id 的解释
• blocklet-spec 右侧边栏有些文本过长
• blocklet cli 里面整个文档的 children 和 components 叫法不一致，我们干脆统一下？都叫 components？
• known-issues 里面的第一个文不对题
• sidebar 中英文都没有翻译？
• meta.js 最好能贴个完整的，逐个字段解释下
• 添加付费组件在 blocklet cli 里面还是不支持的？
• blocklet ui 的包名字都是错的 @blocklet/ui
• navigation、theme、copyright 不应该合并到一起，navigation 是组合型 blocklet 非常重要的话题，需要写的更细，比如如何写，结果是怎样的，自动合并逻辑
• types 的解释也过于简略，相当于没有

• 应用类型放在 reference 或者 conceptual 里面解释比较合适，这里面最好要加上 blocklet server 的运行时差异，bundle 时的差异，补充 https://developer.blocklet.io/docs/zh/reference/blocklet-spec#Types ，然后链接到那里
• 将现有项目转为 blocklet 里面缺少其他的必要文件，比如 logo、blocklet.md，力争参照这个步骤做出来的应用能直接打包并传到 store 上面

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: 创建应用
• Content Source: developer/docs/pages/how-to/create/index.zh.md
• Version: 0.1.75

[Enter feedback here]

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Welcome
• Content Source: developer/docs/pages/welcome.zh.md
• Version: 0.1.67

[Enter feedback here]

第一段中链接书写形式错了
[创建第一个网站]（/quick-start/create-blocklet）

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: 入门指南
• Content Source: developer/docs/pages/quick-start/index.zh.md
• Version: 0.1.90

可以参考的：https://github.com/meilisearch?type=source

当 blocklet 作为组件被挂碍时，跳转不正确 https://developer.blocklet.io/docs/welcome

文档结构调整为：

• 部署到远程
  • 创建 Access Key
  • 把 blocklet 部署到远程
  • 把 component 部署到远程
  • 使用 github actions 自动化
• 部署到本地
  • 把 blocklet 部署到本地
  • 把 component 部署到本地
  • 使用 github actions 自动化

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Deploy blocklet directly to the server
• Content Source: developer/docs/pages/how-to/deploy/index.zh.md
• Version: 0.1.75

1. 给出完整的 action workflow 的例子，分别是单个 repo，monorepo 下面，先标明目录结构，然后是 action workflow 配置，也可以给出我们一些可以参考的 public repo 的链接，供参考
2. 是否跳过 blocklet-server 环境准备步骤，默认为 false --> 指的是 blocklet cli 安装步骤？因为打包、上传、部署，基本和 server 无关
3. blocklet store 链接到官方的 store

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Github Actions
• Content Source: developer/docs/pages/reference/blocklet-actions/index.zh.md
• Version: 0.1.76

• 权限控制模型的详细解释应该放在 conceptual guide 里面，具体应该包括
  • 基本模型
  • 默认的角色，角色和通行证的关系
  • 默认的权限
  • 默认的角色权限绑定
  • 用户认证流程
• 文档结构看起来很乱，不是从解决某个问题出发的，建议从开发者可能关心的问题出发
  • 如何获得用户？通过 AuthService，或者通过 DIDConnect，或者直接跳转到 AuthService 的登陆页？
  • 如何管理用户？Revoke、Approve
  • 如何管理角色？创建、查询、删除，有用户的角色能删么？
  • 如何管理用户权限？如何授权、取消授权，如何查询权限
  • 如何给用户发通行证？代码、邀请链接

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: 用户和通行证
• Content Source: developer/docs/pages/how-to/auth/index.zh.md
• Version: 0.1.75

• 中文页面下的内容还是英文的？
• 每个命令下至少有个输出的例子？
• 中文、英文模式下的页面 title、description

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Blocklet CLI
• Content Source: developer/docs/pages/reference/blocklet-server-cli/index.zh.md
• Version: 0.1.76

[Enter feedback here]
blocklet service 这里需要更多的说明文档，说明每个service 是什么。

目前只是一句话。 每个service 都值得有自己的一个或多个 page

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Blocklet Service
• Content Source: developer/docs/pages/reference/blocklet-service/index.zh.md
• Version: 0.1.98

• 中文页面下的内容还是英文的？
• typo：./blocklet/bundle，并且这里应该链接到 bundle 的参考文档
• 每个命名下至少有个输出的例子？
• 中文、英文模式下的页面 title、description

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Blocklet CLI
• Content Source: developer/docs/pages/reference/blocklet-cli/index.zh.md
• Version: 0.1.76

https://github.com/ArcBlock/blocklet-server/pull/5498

https://github.com/meilisearch/meilisearch/releases/tag/v0.29.0

比如 /.well-known/service/lost-passport

• 通过 blocklet sdk 获取 blocklet 当前是 dev 还是 production

const { env } = require('@blocklet/sdk)

env.mode === 'development' // 开发环境

env.mode === 'production' // 正式环境

• meta.js 是什么？
• meta.js 如何构造出来？
• 如何加载？js、json
• 如何使用？

/admin/blocklets/z8ia4e5vAeDsQEE2P26bQqz9oWR1Lxg9qUMaV/configuration

比如：

• BLOCKLET_APP_NAME
• BLOCKLET_APP_DESCRIPTIOn
• BLOCKLET_PASSPORT_COLOR
• BLOCKLET_APP_URL
• BLOCKLET_APP_LOGO
• BLOCKLET_APP_LOGO_SQUARE
• BLOCKLET_APP_SK
• BLOCKLET_DELETABLE
• BLOCKLET_WALLET_TYPE

• 比如发送简单的文本、vc、nft、token

Document Details

• AppId: zNKh7m9JccKmZY8vCSbkdYVoXem5CceAiYD1
• Content: Communicate with DID Wallet
• Content Source: developer/docs/pages/how-to/notification/index.md
• Version: 0.1.88

呈现方式

• 所有的 Demo 都有豆腐块的方式展示出来，包含封面图、Store 链接、Repo 链接、文章链接
• 可以包含我们官方的 Demo，社区用户产生的 Demo

用户价值

1. 开发者可以通过 demo 卡片了解 blocklet 平台的能力
2. 开发者可以通过安装 demo 体验 blocklet 平台的功能
3. 开发者可以通过 demo 源码学习 blocklet 功能的实现方式

Demo 文档

每个 Demo 的文档放在文档站下面：https://developer.blocklet.io/docs/samples/simple-html-demo ，这篇文章应该遵循如下的提纲：

• 为什么做这个 Demo？
• 展示了 Blocklet 平台哪些能力？
• 基本实现思路
• 关键代码解释
• 知识点文档链接：行文中就可以包括进去
• Store、Repo 链接

应该支持的 Demo 列表

这个列表纪要能展示我们的平台能力，也要能 cover 常见应用开发的需求：比如用户管理、权限管理、数据持久化

• 不同类型的 blocklet
  • static
  • dapp
  • group
• 展示 blocklet service 能力
  • auth：用户认证、权限控制
  • notification：给用户发通知，收发用户消息
• 展示可组合能力的
  • 组合前端：blocklet-ui
  • 组合控制台：blocklet-ui
  • 嵌套的组合
• 展示盈利能力的
  • 组件付费
  • 组合付费
• 展示和链交互能力的
  • ethereum 链
  • ocap 链
• 展示 did-connect 能力的
  • 可以链接到 did-connect 站点
• 展示 nft 能力的
  • asset
  • factory
• 展示 xmark 能力的
  • pages
  • docs
• 展示主流框架支持能力的
  • react
  • vue

现有 Demo 列表

这个列表应该适配到上面的列表中去

• Simple HTML Demo: 最简单的 blocklet
• 2048 Demo: 将静态站点封装为 blocklet
• React Demo: 使用 react 开发 blocklet
• Blocklet Page Demo: 使用 blocklet page 开发 blocklet
• Auth Demo: 演示权限管理能力，Passport 使用
• Notification Demo: 演示 Blocklet 的通知能力
• Component Demo: 演示组合 Blocklet
• DID Connect Demo: 使用 DID Connect
• 更多的需要整理进来

目前storybook 中有 demo，但是没有 api 文档

需求，直接查阅组件的某个属性是什么意思，如何使用。比如 Dashboard 中的 invalidPathFallback

https://developer.blocklet.io/docs/en/apis/docs/en/deployment/bundle

参照目前规划的结构，以及

• https://github.com/ArcBlock/blocklet-server/issues/5370

目前这个链接跳转到 Introduction 页面，但是我点这个链接明显是想快速start，而且介绍页面还有 Server和 Store的概念，感觉会让人有点疑惑。

是否可以直接跳去
https://blocklet-developer-site-r2m-18-180-145-193.ip.abtnet.io/development/getting-started
然后在具体步骤中添加store和 server的介绍链接。（当前的目录结构可以保持不变）　

1. 在 Blocklet Server 创建 accessKey 和 accessToken
2. 打包 blocklet
3. 使用 blocklet deploy .blocklet/bundle --endpoint --access-key --access-token 部署

先确定应该写哪些文档，建议把文档放到 www.blocklet.io 下面

https://developer.blocklet.io/