Part of #8.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

The way readthedocs.io is set up, documentation versions are automatically mapped to branches of the repo. The latest version in each series of Alda releases (e.g. 1.0.X, 1.1.X, 1.2.X...) will have its own version of the documentation, corresponding to the docs folder in that branch of the alda-lang/alda repo.

I like the way the Python documentation site handles this:

https://docs.python.org/3 (landing page)
https://docs.python.org/3/whatsnew/3.6.html (summary of changes since the last minor version, 3.5)
https://docs.python.org/3.6/whatsnew/changelog.html (detailed changelog for this series of releases)

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

Another great idea from @abhi18av:

Also I feel we need to expand on the examples to something more like a gallery.

I think an "Example Scores" section would be nice. We could adapt the example scores in the alda-core repo and come up with a cohesive set of examples that serve as good demos for Alda's features.

The example scores in the alda-core repo are used for automated testing, so many of them are not really the best demos. We should think about which ones to include and possibly about adding additional examples.

EDIT 2024-03-19: updated example scores link

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

The Community section should include links to/information about:

• the Alda Slack group
• the /r/alda subreddit
• the Alda GitHub organization
• contributing to Alda

See #8 for context.

I think the Python documentation is a good source of inspiration. There are some nice features here:

• The documentation is available by release version. For example, if you're using Python 3.5 instead of 3.6, you can find the latest 3.5 version (i.e. 3.5.3) docs here.

• The landing page has big links to the most relevant information, like the changelog, a tutorial, installation instructions, an FAQ, etc.

• As you navigate through the docs, there is a sidebar with quick links to each section, making it easy to zero in on a particular section.

I previously looked into http://readthedocs.io, and it seems like a nice way to set up something like this. I did a quick port of our existing documentation here: http://alda.readthedocs.io/en/latest/

The docs are actually generated from the alda-lang/alda repo, which is great because we can still keep the docs version controlled alongside the source code, and easily generate different versions of the documentation based on Alda release versions.

The next steps are to organize the docs better so that they look good on readthedocs.io, and then we could CNAME the docs to something like http://docs.alda.io and include a link on the website.

Looks like the website is returning a 404 error when one tries to access the cheat sheet page at https://alda.io/cheat-sheet.
(I just clicked on "Cheat sheet" on the navbar.)

Depending on the layout, I could make an alternate version of the alda logo that has the full word "alda" instead of just the "a"

Alda doesn't yet have an "official" logo -- if/when we do, we should clearly display it on the website 😛

Related: alda-lang/alda#50

Right now alda.io is just a placeholder. We need a decent layout and some basic content, for starters. At the moment, we're getting a lot of mileage out of having all of our info, releases, examples, documentation in the alda-lang/alda GitHub repo, but some of the most pertinent content ought to be made available on alda.io, as well.

Some ideas:

• Basic introductory information
• Example scores showcasing features of Alda
• A download link for the latest release
• Release notes / other blog posts
• Some small amount of documentation? I think that GitHub is the best place to keep Alda's documentation, as we manage it in version control along with the source code. It occurred to me that we could have nicer looking documentation on alda.io, but I think it might be better to have a "Quick Start" page on alda.io just to give visitors a basic idea of how to use it. This page would link to the official docs in the GitHub repo for more in-depth documentation.

If you're here reading this, please share your thoughts! What would you like to see when you go to Alda's official website?

Moved from alda-lang/alda#50.

You can see our current logo here: https://github.com/alda-lang

It's something I hacked together in GIMP late one night because I was tired of looking at the default org logo generated by GitHub.

What I would love, though, is for someone with better graphic design skills than I to come up with something more pleasing to the eye.

I'm thinking something that doesn't have the word "alda" on it. Maybe some kind of stylized "A"? The name Alda comes from the Quenya word for "tree," so something tree-related might be cool, but that's not a requirement.

A number of possible logos have been proposed in the original issue, but I am still looking for the perfect Alda logo.

By the way, I really appreciate all of the proposed logos so far! I apologize that I'm being so picky about this. Alda is very near & dear to my heart, and my standards about its logo design are high.

Please don't be discouraged if I've passed on your logo so far. 😅

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

Quoting myself:

I made a quick sketch of what these sections might look like:

From the landing page, sections could include:

• What's new in Alda 1.0.0? (1.1.0, 1.2.0, etc.)
• Setup and Usage
• Tutorial (see below)
• Reference (would include things like...)
  • list of instruments
  • list of attributes
  • alda.lisp API docs (i.e. a list of functions available in the alda.lisp namespace, what they do and how to use them)
• The Alda Command-Line Client
• Developer Portal (would include information like...)
  • Using Alda in a Clojure program
  • Technical details about Alda components
  • Writing your own Alda components
  • ZeroMQ architecture
• Community (links to the Alda Slack group, subreddit, GitHub org, etc. and information about contributing to Alda)

Quoting @abhi18av:

@daveyarwood Let's include the your talk videos in the docs.

Alda: A Music Programming Language, Built in Clojure (David Yarwood)

Alda: A text based music composition language

I think we could also include a "Talks and Demos" section where we could include links to the videos above, as well as this excellent demo by @jimcheetham.

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

The Reference section would include information like:

• list of instruments
• list of attributes
• alda.lisp API docs (i.e. a list of functions available in the alda.lisp namespace, what they do and how to use them)

The installation guide's final example command: alda play -c '(tempo! 160) trumpet: (quant 60) f12 b- > d f6 d12 f1' doesn't work on windows producing "No Alda source code input supplied." error.
Changing the single quotes to regular ones (alda play -c "(tempo! 160) trumpet: (quant 60) f12 b- > d f6 d12 f1") does the trick.

Not sure if it happens only for me, but thought it's important to either address this as an "alda on windows" bug, or just fix the doc

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

The docs should have a page guiding the reader through:

• Installing Alda
• Learning about MIDI soundfonts and optionally installing one to make Alda sound better
• Learning about the available text editor plugins

This information is currently all in the README:

https://github.com/alda-lang/alda#installation
https://github.com/alda-lang/alda#midi-soundfonts
https://github.com/alda-lang/alda#editor-plugins

Once we've moved it to the docs, we can replace those parts of the README with a link to the docs.

I think this page could also include some very basic usage examples like what we have here, and then suggest that the reader either read the Alda Command-Line Client docs for more technical information, or proceed to the Tutorial section for a guided tour of Alda.

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

This section could include links like the ones I listed on my GitHub sponsors page.

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

Note: no docs currently exist for the Alda CLI client -- this is new territory. I think it would be good to include some practical examples of the Alda command-line workflow using the alda client, some information about Alda server and worker processes, how to play files or strings of code, how to start the REPL, etc.

The header of the website looks OK if the browser is wide:

But if the browser is narrow (e.g. on mobile), the links overflow onto subsequent lines and end up overlapping with the content below:

I'm not very good at CSS, so if anyone is able to help me fix this, I would greatly appreciate it! 🙏

The syntax highlighting looks a little wonky because, with Alda being a new language, Rouge has no idea how to lex and highlight Alda code.

It seems like it shouldn't be too hard to create an Alda lexer for Rouge.

For reference: https://github.com/jneen/rouge#using-the-lexer-dsl

From alda-lang/alda#210, cc: @lifeluvr @elyisgreat @jgkamat

Should be a webpage with concise examples, something like the Emmet cheat sheet.

Reference material currently available:

• September 2015 introduction/tutorial
• November 2015 overview of new features
• Alda docs

See #8 (comment) for context.

The tutorial sections could be something like:

• Anatomy of an Alda Score (a broad overview of the structure of a score file, explaining instrument parts, variable definitions, etc. without going into too much detail)
• Notes and Rests
• Chords and Voices
• Grouping Instruments (covers instrument groups and naming instruments/groups)
• Attributes
• Advanced Rhythms (covers second/millisecond durations and CRAM notation)
• Using Variables
• Generating Music by Writing Code (covers inline Clojure code and an overview of the alda.lisp DSL)

This is just a quick sketch; I'm definitely open to any suggestions about how to tweak this, but maybe this outline can be a good starting point.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

See #8 for context.

This should be done by modifying the docs folder in alda-lang/alda. The docs are kept in sync with releases and used to generate http://alda.readthedocs.io, which will be CNAMEd to docs.alda.io.

The Alda Developer Portal will be a place for technical details not necessarily relevant to the typical end-user, but useful for developers who want to know how Alda works under the hood.

It should include information about things like:

• Using Alda in a Clojure program
• Technical details about Alda components
• Writing your own Alda components
• ZeroMQ architecture Alda player OSC API

🐞 Bug report 🐞

your page has responsive issues

Description

when it comes to mobile view the content in the navbar section overflows through the home section

Assign me I can fix this bug

Currently we do not support https://alda.io, only http://alda.io.

We should get an SSL certificate, maybe through https://letsencrypt.org, and figure out how to set it up through GitHub Pages so that we support https too.

Then, we should always redirect http => https.

Continuing the conversation from #1 / #7 (cc: @abhi18av):

Alda's documentation currently lives as a series of unorganized Markdown files in the main Alda repo. My initial thought was that the documentation could be managed in version control alongside the source code, which is compelling.

However, I think it's more important to have helpful, well-organized documentation available on alda.io, with more of a focus on making it easier to find the information you're looking for.

I think the Python documentation is a good source of inspiration. There are some nice features here:

• The documentation is available by release version. For example, if you're using Python 3.5 instead of 3.6, you can find the latest 3.5 version (i.e. 3.5.3) docs here.

• The landing page has big links to the most relevant information, like the changelog, a tutorial, installation instructions, an FAQ, etc.

• As you navigate through the docs, there is a sidebar with quick links to each section, making it easy to zero in on a particular section.

I previously looked into http://readthedocs.io, and it seems like a nice way to set up something like this. I did a quick port of our existing documentation here: http://alda.readthedocs.io/en/latest/

The docs are actually generated from the alda-lang/alda repo, which is great because we can still keep the docs version controlled alongside the source code, and easily generate different versions of the documentation based on Alda release versions.

The next steps are to organize the docs better so that they look good on readthedocs.io, and then we could CNAME the docs to something like http://docs.alda.io and include a link on the website.