Skip to content

Commit abaec32

Browse files
conwnetconwnet
authored
docs: update docs (#749)
1 parent 40b962c commit abaec32

16 files changed

Lines changed: 673 additions & 338 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -1,198 +1,67 @@
1-
![GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/logo.svg)
1+
![GitHub1s](resources/images/logo.svg)
22

3-
# github1s
3+
# GitHub1s
44

5-
One second to read GitHub code with VS Code.
5+
GitHub1s is a browser-based code explorer built on VS Code. Browse files, search code, and review changes without cloning a repository. Connect your preferred model to the built-in AI chat for help understanding the code.
66

7-
## Usage
7+
**[🌐 Try it now](https://github1s.com/conwnet/github1s)** · [📖 Usage guide](docs/usage.md) · [🔮 AI setup](docs/ai.md#configure-a-model)
88

9-
Just add `1s` after `github` and press `Enter` in the browser address bar for any repository you want to read.
9+
## 🚀 Quick start
1010

11-
For example, try it on the VS Code repo:
11+
Add **`1s` after `github`** in a repository URL:
1212

13-
[https://github1s.com/microsoft/vscode](https://github1s.com/microsoft/vscode)
14-
15-
![VS Code - GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/vs-code-github1s.png)
16-
17-
You can also use [https://gitlab1s.com](https://gitlab1s.com) or [https://npmjs1s.com](https://npmjs1s.com) in the same way.
18-
19-
For browser extensions, see [Third-party Related Projects](https://github.com/conwnet/github1s#third-party-related-projects).
20-
21-
Or save the following code snippet as a bookmarklet, you can use it to quickly switch between github.com and github1s.com (GitHub markdown doesn't allow js links, so just copy it into a bookmark).
22-
23-
```
24-
javascript: window.location.href = window.location.href.replace(/github(1s)?.com/, function(match, p1) { return p1 ? 'github.com' : 'github1s.com' })
13+
```text
14+
https://github.com/microsoft/vscode
15+
↓
16+
https://github1s.com/microsoft/vscode
2517
```
2618

27-
### Develop in the cloud
28-
29-
To edit files, run Docker containers, create pull requests and more, click the "Develop your project on [Gitpod](https://www.gitpod.io)" button in the status bar. You can also open the Command Palette (default shortcut `Ctrl+Shift+P`) and choose `GitHub1s: Edit files in Gitpod`.
30-
31-
![Gitpod Status Bar](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/gitpod-statusbar.png)
32-
33-
## Documentation
34-
35-
- [How it works](https://github.com/conwnet/github1s/blob/master/docs/guide.md)
36-
- [Roadmap](https://github.com/conwnet/github1s/projects/1)
37-
38-
## Enabling Private Repositories
39-
40-
If you want to view non-public repositories, you need to add an OAuth token. The token is stored only in your browser, and only send to GitHub when fetching your repository's files. Click on the icon near the bottom of the left-hand row of icons, and the dialog box will prompt you for it, and even take you to your GitHub settings page to generate one, if needed.
41-
42-
<img height="500px" src="https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/auth-token.png" />
43-
44-
## Screenshots
45-
46-
![VS Code - GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/GitHub1sDemo1.gif)
47-
48-
![VS Code - GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/demo.png)
49-
50-
## Development
51-
52-
### Cloud-based development
53-
54-
You can start an online development environment with [Gitpod](https://www.gitpod.io) by clicking the following button:
55-
56-
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/conwnet/github1s)
57-
58-
### Local development
59-
60-
```bash
61-
git clone git@github.com:conwnet/github1s.git
62-
cd github1s
63-
npm install
64-
npm run watch
65-
# The cli will automatically open http://localhost:8080 once the build is completed.
66-
# You can visit http://localhost:8080/conwnet/github1s if it doesn't.
67-
```
68-
69-
#### Local development with full VS Code build
70-
71-
You need [these prerequisites (the same ones as for VS Code)](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites) for development with full VS Code build.
72-
Please make sure you could build VS Code locally before the watch mode.
73-
74-
To verify the build:
75-
76-
```bash
77-
cd github1s
78-
npm run build:vscode
79-
```
80-
81-
After the initial successful build, you could use the watch mode:
82-
83-
```bash
84-
cd github1s
85-
npm install
86-
npm run watch-with-vscode
87-
# The cli will automatically open http://localhost:8080 once the build is completed.
88-
# You can visit http://localhost:8080/conwnet/github1s if it doesn't.
89-
```
90-
91-
### ... or ... VS Code + Docker Development
92-
93-
You can use the VS Code plugin [Remote-Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) `Dev Container` to use a Docker container as a development environment.
94-
95-
1. Install the Remote-Containers plugin in VS Code & Docker
96-
2. Open the Command Palette (default shortcut `Ctrl+Shift+P`) and choose `Remote-Containers: Clone Repository in Container Volume...`
97-
3. Enter the repo, in this case `https://github.com/conwnet/github1s.git` or your forked repo
98-
4. Pick either, `Create a unique volume` or `Create a new volume`
99-
100-
- Now VS Code will create the docker container and connect to the new container so you can use this as a fully setup environment!
101-
102-
5. Open a new VS Code Terminal, then you can run the `npm install` commands listed above.
103-
104-
```bash
105-
npm install
106-
npm run watch
107-
# The cli will automatically open http://localhost:8080 once the build is completed.
108-
# You can visit http://localhost:8080/conwnet/github1s if it doesn't.
109-
```
110-
111-
### Format all codes
112-
113-
```bash
114-
npm run format
115-
```
116-
117-
It uses `prettier` to format all possible codes.
118-
119-
## Build
120-
121-
```bash
122-
npm install
123-
npm run build
124-
```
125-
126-
## Feedback
127-
128-
- If something is not working, [create an issue](https://github.com/conwnet/github1s/issues/new)
129-
130-
## Sponsors
131-
132-
The continued development and maintenance of GitHub1s is made possible by these generous sponsors:
19+
Public repositories can be browsed **without signing in**, subject to the upstream services' access and rate limits.
13320

134-
<table><tbody><tr>
135-
<td><a href="https://sourcegraph.com/">
136-
<img height="40px" src="https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/sourcegraph-logo.svg">
137-
</a></td>
138-
</tr></tbody></table>
21+
![A repository open in GitHub1s, with the file explorer and README preview](resources/images/demo.png)
13922

140-
## Partners
23+
You can also browse GitLab repositories at [gitlab1s.com](https://gitlab1s.com) and published npm packages at [npmjs1s.com](https://npmjs1s.com). See the [usage guide](docs/usage.md) for URL formats, authentication, and navigation.
14124

142-
We are partnered with [OSS Insight](https://ossinsight.io/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending) to get the Trending Repositories & some more Interesting Analytics. [OSS Insight](https://ossinsight.io/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending) provides deep insights into GitHub repos, developers, and curated repo lists from billions of GitHub events. It’s built with [TiDB Cloud](https://www.pingcap.com/tidb-cloud/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending).
25+
## ✨ Features
14326

144-
<table><tbody><tr>
145-
<td><a href="https://ossinsight.io/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending">
146-
<img height="40px" src="./resources/images/ossinsight-brand-dark.png">
147-
</a></td>
148-
</tr></tbody></table>
27+
- **Explore a project.** Browse directories, find files, and search code in a familiar VS Code interface.
28+
- **Trace a change.** Switch branches or tags, inspect commits and file history, and review pull or merge request diffs on GitHub and GitLab.
29+
- **Understand complex code.** Ask GitHub1s AI about a file or selection, then follow up on implementation details.
30+
- **Access private repositories.** Connect your GitHub or GitLab account, or supply an access token with the necessary permissions.
14931

150-
## Maintainers! :blush:
32+
Remote repositories are **read-only**. Search and code navigation depend on the repository platform and available upstream services; see [capabilities and limits](docs/usage.md#capabilities-and-limits).
15133

152-
<table>
153-
<tbody><tr>
154-
<td align="center"><a href="https://github.com/conwnet"><img alt="" src="https://avatars.githubusercontent.com/conwnet" width="100px;"><br><sub><b>netcon</b></sub></a><br><a href="https://github.com/conwnet/github1s/commits?author=conwnet" title="Code">💻 🖋</a></td> </a></td>
155-
<td align="center"><a href="https://github.com/xcv58"><img alt="" src="https://avatars.githubusercontent.com/xcv58" width="100px;"><br><sub><b>xcv58</b></sub></a><br><a href="https://github.com/conwnet/github1s/commits?author=xcv58" title="Code">💻 🖋</a></td></a></td>
156-
<td align="center"><a href="https://github.com/Siddhant-K-code"><img alt="" src="https://avatars.githubusercontent.com/Siddhant-K-code" width="100px;"><br><sub><b>Siddhant Khare</b></sub></a><br><a href="https://github.com/conwnet/github1s/commits?author=Siddhant-K-code" title="Code">💻 🖋</a></td> </a></td>
157-
</tr>
158-
</tbody></table>
34+
## 🤖 GitHub1s AI
15935

160-
## Stargazers over time
36+
Get a repository overview, explain a file or selection, and ask follow-up questions. The assistant can look up relevant code as you chat.
16137

162-
[![Stargazers over time](https://api.star-history.com/svg?repos=conwnet/github1s&type=Date)](https://star-history.com/#conwnet/github1s&Date)
38+
Click **Toggle Secondary Side Bar** in the layout controls at the top of GitHub1s to open the AI panel.
16339

164-
<details>
165-
<summary>Third-party Related Projects</summary>
166-
<br>
40+
Use a **model endpoint that accepts browser requests**. Messages and code context are sent to the selected endpoint. See the [AI guide](docs/ai.md) for configuration and data handling.
16741

168-
### Chrome Extensions
42+
## 📚 Documentation
16943

170-
- [Repositree](https://chrome.google.com/webstore/detail/repositree/lafjldoccjnjlcmdhmniholdpjkbgajo) ([chouglesaud/repositree](https://github.com/chouglesaud/repositree))
171-
- [github-code-viewer](https://chrome.google.com/webstore/detail/github-code-viewer/ecddapgifccgblebfibdgkagfbdagjfn) ([febaoshan/edge-extensions-github-code-viewer](https://github.com/febaoshan/edge-extensions-github-code-viewer))
172-
- Github1s Extension ([Darkempire78/GitHub1s-Extension](https://github.com/Darkempire78/GitHub1s-Extension))
173-
- [Github Web IDE](https://chrome.google.com/webstore/detail/adjiklnjodbiaioggfpbpkhbfcnhgkfe) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE))
174-
- [shortcut to github1s](https://chrome.google.com/webstore/detail/shortcut-to-github1s/gfcdbodapcbfckbfpmgeldfkkgjknceo) ([katsuhisa91/github1s-shortcut](https://github.com/katsuhisa91/github1s-shortcut))
175-
- [Github1s Shortut - Open source](https://github.com/Fauzdar1/Github1s)
176-
- [⚡️ 1s to GitHub1s!](https://github.com/holazz/webext-github1s)
177-
- [github1s Google Chrome Extensions](https://github.com/Lonely-Mr-zhang/github_1s_vscode)
44+
| Guide | What you will find |
45+
| ------------------------------------ | ------------------------------------------------------- |
46+
| [Using GitHub1s](docs/usage.md) | Navigation, authentication, search, and troubleshooting |
47+
| [GitHub1s AI](docs/ai.md) | Model setup, context, tools, and data handling |
48+
| [Development](docs/development.md) | Local setup, builds, and checks |
49+
| [Architecture](docs/architecture.md) | Components, data flow, and source layout |
50+
| [Deployment](docs/deployment.md) | Hosting, OAuth, and service configuration |
51+
| [Community](docs/community.md) | Third-party extensions and star history |
17852

179-
### Firefox Extensions
53+
## 🤝 Contributing
18054

181-
- [Repositree](https://addons.mozilla.org/en-US/firefox/addon/repositree/) ([chouglesaud/repositree](https://github.com/chouglesaud/repositree))
182-
- [Github1s Extension](https://addons.mozilla.org/firefox/addon/github1s-extension) ([Darkempire78/GitHub1s-Extension](https://github.com/Darkempire78/GitHub1s-Extension))
183-
- [Github1s](https://addons.mozilla.org/firefox/addon/github1s/) ([mcherifi/github1s-firefox-addon](https://github.com/mcherifi/github1s-firefox-addon))
184-
- [Github Web IDE](https://addons.mozilla.org/firefox/addon/github-web-ide/) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE))
55+
See the [development guide](docs/development.md) to run GitHub1s locally. Report bugs and suggest improvements through [GitHub Issues](https://github.com/conwnet/github1s/issues).
18556

186-
### Microsoft Edge Extensions
57+
## 👥 Maintainers
18758

188-
- [github-code-viewer](https://microsoftedge.microsoft.com/addons/detail/githubcodeviewer/jaaaapanahkknbgdbglnlchbjfhhjlpi) ([febaoshan/edge-extensions-github-code-viewer](https://github.com/febaoshan/edge-extensions-github-code-viewer))
189-
- [Github Web IDE](https://microsoftedge.microsoft.com/addons/detail/akjbkjciknacicbnkfjbnlaeednpadcf) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE))
59+
[conwnet](https://github.com/conwnet) · [xcv58](https://github.com/xcv58) · [Siddhant Khare](https://github.com/Siddhant-K-code)
19060

191-
### Safari Extension
61+
## 💖 Acknowledgments
19262

193-
- [GitHub1s-For-Safari-Extension](https://apps.apple.com/us/app/readcodeonline/id1569026520?mt=12) ([code4you2021/GitHub1s-For-Safari-Extension](https://github.com/code4you2021/GitHub1s-For-Safari-Extension))
63+
Thanks to everyone who has contributed to GitHub1s, and to [Sourcegraph](https://sourcegraph.com/), [searchcode](https://searchcode.com/), and [OSS Insight](https://ossinsight.io/) for their support of the project.
19464

195-
### Tampermonkey scripts
65+
## 📄 License
19666

197-
- [Mr-B0b/TamperMonkeyScripts/vscode.js](https://github.com/Mr-B0b/TamperMonkeyScripts/blob/main/vscode.js)
198-
</details>
67+
[MIT](LICENSE)

0 commit comments

Comments
 (0)