docs: Readme.md for docs and guide/index additions (#1773)
Daryl White
GitHub
parent
b7e565dedc
commit
76efc724eb
|
|
@ -4,6 +4,8 @@ Hi! We are really excited that you are interested in contributing to Elk. Before
|
|||
|
||||
Refer also to https://github.com/antfu/contribute.
|
||||
|
||||
For guidelines on contributing to the documentation, refer to the [docs README](./docs/README.md).
|
||||
|
||||
### Online
|
||||
|
||||
You can use [StackBlitz Codeflow](https://stackblitz.com/codeflow) to fix bugs or implement features. You'll also see a Codeflow button on PRs to review them without a local setup. Once the elk repo has been cloned in Codeflow, the dev server will start automatically and print the URL to open the App. You should receive a prompt in the bottom-right suggesting to open it in the Editor or in another Tab. To learn more, check out the [Codeflow docs](https://developer.stackblitz.com/codeflow/what-is-codeflow).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,101 @@
|
|||
# Welcome to the Elk Docs
|
||||
|
||||
The documentation site publishes to https://docs.elk.zone.
|
||||
We use [Docus](https://docus.dev) as the site generator and deploy through Netlify.
|
||||
|
||||
## Quickstart
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Github account
|
||||
- Git installed on your machine
|
||||
- Node >14.18 installed
|
||||
- Use `node -v` to see which version you have installed.
|
||||
- Use `nvm install node` to upgrade to the latest version.
|
||||
- Refer to the [nvm docs](https://github.com/nvm-sh/nvm#installing-and-updating) for information on installing `nvm`.
|
||||
- [pnpm](https://pnpm.io/installation) installed
|
||||
|
||||
### Install and Preview
|
||||
|
||||
1. [Fork the Elk Github project](https://github.com/elk-zone/elk/fork) into your own account
|
||||
2. Clone your fork to your local machine
|
||||
3. From your terminal, `cd` to the directory you cloned into
|
||||
4. `cd docs` to enter the docs folder
|
||||
5. Run `npm install`
|
||||
Note: Run this from the project's `docs` folder, not the root of the repository on your machine!
|
||||
6. Run `npm run dev` to launch a preview
|
||||
7. Visit `localhost:3000/docs/` to see a live preview of the docs
|
||||
|
||||
### Contributing
|
||||
|
||||
When you are ready to submit work back to the main Elk repo, create a PR.
|
||||
|
||||
1. If it has been a bit, synchronize your fork with the upstream repo on Github.
|
||||
2. Do your work in a branch on your fork
|
||||
Use `git checkout -b branchNameToUse` to create a working branch separate from `main`.
|
||||
3. Do your work in your preferred editor
|
||||
4. Commit changes often and write meaningful commits
|
||||
5. Push the changes from your local machine to your fork on Github
|
||||
6. Go to your fork of the Elk project in your Github account
|
||||
7. Select the **Pull Request** tab
|
||||
8. Select **New Pull Request**
|
||||
9. Confirm the repo/branches to compare
|
||||
- Base repo should be **elk-zone/elk**
|
||||
- base branch should be **main**
|
||||
- Head repository should be your fork
|
||||
- Compare branch should be your working branch you want to submit
|
||||
If you don't see four drop downs, be sure you are comparing across forks.
|
||||
10. Add a description of the changes your request makes
|
||||
11. Select **Add Pull Request**
|
||||
|
||||
Other team members will review your PR and make comments or suggestions through the PR.
|
||||
You can continue making additional changes and/or apply feedback by making additional commits to the branch on your fork.
|
||||
ALWAYS WORK IN YOUR FORK/BRANCH.
|
||||
|
||||
## Writing
|
||||
|
||||
### Tips
|
||||
|
||||
- Docs are in the `docs/content` folder
|
||||
- Write in standard markdown
|
||||
- Refer to the Docus [writing pages](https://docus.dev/introduction/writing-pages) guide
|
||||
- Docus provides additional [components](https://docus.dev/api/components) to extend basic markdown
|
||||
|
||||
Avoid screenshots until Elk reaches a stable release.
|
||||
|
||||
### Standards
|
||||
|
||||
Write in **American English** using spelling as found in [Merriam Webster](https://www.merriam-webster.com).
|
||||
Translation and localization will be handled separately as/when availability or necessity allow.
|
||||
|
||||
Use [**semantic linefeeds**](https://rhodesmill.org/brandon/2012/one-sentence-per-line/) with no more than one sentence per line.
|
||||
To create paragraphs, use a blank line.
|
||||
|
||||
There are no house style rules currently.
|
||||
When we add any, they will be found in this document.
|
||||
|
||||
#### Style Guides
|
||||
|
||||
Use the first guide that mentions a usable standard from the order below:
|
||||
|
||||
1. Refer to the U.S. Government's [Federal Plain Language Guidelines](https://www.plainlanguage.gov/guidelines/) as a base standard.
|
||||
2. For user interface, device, and other technical guidance, refer to [**Google's Developer Style Guide**](https://developers.google.com/style).
|
||||
3. As a secondary reference to the Google guide, refer to [Microsoft's Style Guide](https://docs.microsoft.com/style-guide/welcome/), then the [Chicago Manual of Style, 17th Edition](https://www.chicagomanualofstyle.org/home.html).
|
||||
|
||||
We use [Merriam-Webster](https://www.merriam-webster.com/) as the standard dictionary for spelling.
|
||||
|
||||
### Images
|
||||
|
||||
Place image files in the /docs/public/images folder.
|
||||
You can create subfolders to organize the images.
|
||||
|
||||
To add an image to a doc, use standard markdown:
|
||||
|
||||
```md
|
||||
[](URL.for.hyperlink)
|
||||
[](https://stackblitz.com/)
|
||||
```
|
||||
|
||||
## In-house Styles
|
||||
|
||||
None yet defined
|
||||
|
|
@ -2,25 +2,98 @@
|
|||
|
||||
## What is Elk?
|
||||
|
||||
::alert{type=warning}
|
||||
🚧 This section is a work in progress. 🚧
|
||||
::
|
||||
Elk is an alternative way to access your Mastodon account from your browser.
|
||||
|
||||
Through the Mastodon API, Elk provides similar access to posts and actions on posts you expect to be able to do to Mastodon.
|
||||
You can compose a post (Toot, if you like), boost others' toots, like, bookmark, and scroll just as you would through your regular server site.
|
||||
|
||||
Why Elk, then?
|
||||
Elk provides some features not available through the standard Mastodon web app interface.
|
||||
|
||||
- Notifications for the same post combine when they are sequential. No more seeing your same viral joke multiple times in the Notification feed for each like and boost. Now you can see it just one, with a list of who liked or boosted the post just above the post itself.
|
||||
- You control whether you see boost, like, and follower accounts - all separately!
|
||||
- See a preview of the profile when someone follows you.
|
||||
|
||||
You can use Elk right in your browser.
|
||||
On a mobile device, you can install the app to your home screen right from your browser for easy access.
|
||||
(This is called a Progressive Web App, or [PWA](../80.pwa.md).)
|
||||
|
||||
Want to try it out?
|
||||
Visit https://elk.zone, type in your Mastodon server address, then log in.
|
||||
Or, visit one of the other Elk installs in the [Elk ecosystem](https://github.com/elk-zone/elk#ecosystem).
|
||||
|
||||
## What is Mastodon?
|
||||
<!-- -> external links -->
|
||||
|
||||
::alert{type=warning}
|
||||
🚧 This section is a work in progress. 🚧
|
||||
::
|
||||
Mastodon is a decentralized microblogging platform.
|
||||
Mastodon uses the [ActivityPub protocol](https://www.w3.org/TR/activitypub/) to share posts and actions between users within or across different instance servers.
|
||||
|
||||
You can think of the service as something similar to Twitter, but with some key differences.
|
||||
|
||||
- Where Twitter is a single site that everyone who uses it belongs to, Mastodon is a platform used by many different sites.
|
||||
- Where Twitter is a corporation with profit goals and advertisements, Mastodon is a free and open source software tool maintained by volunteers and paid for by patrons and voluntary contributors to their own instance servers and back to the main software project.
|
||||
- Where Twitter users can only interact with other Twitter users, Mastodon users can talk to users on many other ActivityPub platforms, including services that provide video (PeerTube), photos ([PixelFed](https://pixelfed.org/)), blogs ([WriteFreely](https://writefreely.org/)), and alternative microblogging platforms ([Pleroma](https://pleroma.social/), [Hometown](https://github.com/hometown-fork/hometown), [GoToSocial](https://gotosocial.org/), and their derivatives).
|
||||
|
||||
For more details about Mastodon, see their [website](https://joinmastodon.org/), [blog](https://blog.joinmastodon.org), [docs](https://docs.joinmastodon.org), and [GitHub Repository](https://github.com/mastodon/mastodon).
|
||||
|
||||
|
||||
## What is a Mastodon Client?
|
||||
|
||||
<!-- -> other examples -->
|
||||
A Mastodon Client is software that serves up the posts and activities from a Mastodon server using the [Mastodon API](https://docs.joinmastodon.org/api/).
|
||||
When you visit or sign in to a Mastodon server, you use the standard Mastodon client or the alternative Advanced Web Interface (that provides a multi-column format).
|
||||
|
||||
::alert{type=warning}
|
||||
🚧 This section is a work in progress. 🚧
|
||||
A Mastodon client performs similar functions as the standard web interfaces.
|
||||
Using a client, you can
|
||||
- View posts from accounts you follow
|
||||
- Boost, like, or bookmark posts
|
||||
- Create new posts from your own account
|
||||
- Explore the home, local, and federated timelines
|
||||
- See what is trending on your server
|
||||
- View, add, or participate in polls
|
||||
- Follow, unfollow, mute, and block accounts
|
||||
|
||||
::alert{type="info"}
|
||||
**Note:** Not all clients provide all features.
|
||||
::
|
||||
|
||||
### Installed Mastodon Clients
|
||||
|
||||
You may be most familiar with Mastodon Clients through your phone or tablet.
|
||||
The app you download from an app store and install on your device to access your Mastodon account is a Mastodon Client.
|
||||
|
||||
::card{icon="logos:android-icon"}
|
||||
#title
|
||||
Android
|
||||
#description
|
||||
[Fedilab](https://fedilab.app/), [Tusky](https://tusky.app/), or [Tooot](https://tooot.app/), among others.
|
||||
::
|
||||
|
||||
::card{icon="logos:apple"}
|
||||
#title
|
||||
Apple
|
||||
#description
|
||||
[Ivory](https://tapbots.com/ivory/), [Ice Cubes](https://apps.apple.com/us/app/ice-cubes-for-mastodon/id6444915884), [Metatext](https://github.com/metabolist/metatext), or [Toot](https://apps.apple.com/app/toot/id1229021451?ls=1)
|
||||
::
|
||||
::card{icon="mdi:desktop-classic"}
|
||||
#title
|
||||
Desktop
|
||||
#description
|
||||
[TheDesk](https://thedesk.top/en/), [Whalebird](https://whalebird.social/en), or [Sengi](https://nicolasconstant.github.io/sengi/)
|
||||
::
|
||||
|
||||
|
||||
All of these apps provide some combination of the features a typical Mastodon user expects for their account.
|
||||
|
||||
### Browser-based Mastodon Clients
|
||||
|
||||
Elk is a Mastodon Client, but instead of being an app to install on your phone, tablet, or desktop, it is an alternative web site you visit in a browser.
|
||||
|
||||
In addition to Elk, there are other browser-based alternative Mastodon clients.
|
||||
Some include:
|
||||
|
||||
- [Semaphore](https://semaphore.social/), a continuation of the now-frozen [Pinafore](https://pinafore.social/)
|
||||
- [Sengi](https://nicolasconstant.github.io/sengi/) (Also available as a desktop client)
|
||||
- [Cuckoo](https://cuckoo.social)
|
||||
|
||||
## Sponsors
|
||||
|
||||
We want to thank the generous sponsoring and help of:
|
||||
|
|
|
|||
Loading…
Reference in New Issue